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(54) Compensating resource managers 

(57) A compensating resource manager provides a 
mechanism for more easily integrating non-transac- 
tional durable resources to participate in transactions 
within a component-based on-line transaction process- 
ing system, as well as resources having transaction 
processing support not conforming to the transaction 
processing system. The durable resource is integrated 
using the compensating resource manager by develop- 
ing two sinple components, a worker component that 
implements a normal action on tiie resource and a com- 
pensator component tinat implements a compensating 
action that reverses the normal action on ttie resource. 
The worker component uses system-provided services 

FIG. 3 2ooy^ 



to register its respective compensator component and 
to log information, such as on a wrrte-ahead basis, to 
allow the compensator component to reverse its normal 
action. The system-provided service enlists in a trans- 
action in which the worker component performs its nor- 
mal action to receive two phase commit notifications for 
the transaction, and responsive thereto creates tiie 
compensator component to perform appropriate clean- 
up or compensating action according to the logged 
information depending on whether the transaction com- 
mits or aborts. 
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Description 

HELD OF THE INVENTION 

[0001 ] The present invention relates generally to on- s 
line transaction processing applications, and more par- 
ticularly relates to managing non-transactional 
resources or non>conripliant transactional resources in 
transaction management systems for on-line transac- 
tion processing applications. 

BACKGROUND AND SUMMARY OF THE INVEN- 
TION 

[0002] In many information processing applications, a 
sen/er application running on a host or server computer 
in a distributed network provides processing services or 
methods for client applications running on terminal or 
workstation computers of the network which are oper- 
ated by a multitude of users. Common examples of such 
server applications include software for processing 
class registrations at a university, travel reservations, 
money transfers and other services at a bank, and sales 
at a business. In these examples, the processing serv- 
ices provided by the server application typically main- 
tains persistent data or "state" of class schedules, hotel 
reservations, account balances, order shipments, pay- 
ments, or inventory for actions initiated by the individual 
users at their respective stations, such as in a database 
or other proprietary format data store. 
[0003] Often, server applications require coordinating 
activities on multiple computers, by separate processes 
on one computer, and even within a single process. For 
example, a money transfer operation in a banking appli- 
cation may involve updates to account information held 
in separate databases that reside on separate conput- 
ers that may be geographically remote. Desirably, 
groups of activities that form parts of an operation are 
coordinated so as to take effect as a single indivisible 
unit of worK commonly referred to as a transaction. In 
many applications, performing sets of activities as a 
transaction becomes a business necessity For exam- 
ple, if only one account is updated in a money transfer 
operation due to a system failure, the bank in effect cre- 
ates or destroys money. 

[0004] A transaction is a collection of actions that con- 
form to a set of properties (refen^ed to as the "ACID** 
properties) which include atomicity, consistency, isola- 
tion, and durability. Atomicity means that all activities in 
a transaction either take effect together as a unit, or all 
fa\l Consistency means that after a transaction exe- 
cutes, the system is left in a stable or correct state (i.e., 
if giving effect to the activities in a transaction would not 
result in a correct stable state, the system is returned to 
its initial pre-transaction state). Isolation means the 
transaction is not affected by any other concun^ently 
executing transactions (accesses by transactions to 
shared resources are serialized, and changes to shared 



resources are not visible outside tiie transaction until 
the transaction conpletes). Durability means that the 
effects of a transaction are permanent and survive sys- 
tem failures. For additional background information on 
transaction processing, see, inter alia, Jim Gray and 
Andreas Reuter, Transaction Processing Concepts and 
Techniques, Morgan Kaufmann, 1993. 
[0005] Prior patent applications also assigned to the 
assignee of the current invention (namely Helland et al., 
"Automatic Transaction Processing Of Component- 
Based Server Applications." U.S. Patent Application 
Serial No. 08/959.141; and Helland et al.. "Disabling 
And Enabling Transaction Committal In Transactional 
Application Components," U.S. Patent Application 
Serial No 08/959.142, both filed October 28. 1997; 
which the present application hereby incorporates by 
reference and hereafter refers to collectively as the 
"incorporated MTS Patent Applications") disclose an 
execution environment and platform for distributed 
server applications, which is embodied in the Microsoft 
Transaction Server (MTS) version 1.0 product. MTS 
provides a conponent-based framework or object 
nfKXIel with system services to support transactions by 
potentially distributed groups of components of server 
applications under control of a to-ansaction manager, 
such as the Microsoft Distributed Transaction Coordina- 
tor (MS DTC). 

[0006] tn the MTS, server applications use resource 
managers to maintain the durable state of ttie applica- 
tion, such as tiie record of inventory on hand, pending 
orders, and accounts receivable. Resource managers 
are a system service tiiat manages durable data, such 
as may be contained in databases, durable message 
queues, file systems or other data storage resources. 
One example is the resource manager provided wttii the 
Microsoft SQL Server version 6.5. Resource managers 
operate in cooperation with the transaction manager to 
enforce tiie ACID properties on the durable data of the 
managed resource. 

[0007] Resource managers are difficult to develop and 
implement for a particular resource (e.g.. durable data 
store). This is because a resource manager deals with 
a number of tiie more complex issues in ta'ansaction 
processing. Specifically, the resource manager must 
properly interface with tiie transaction manager, and 
guarantee tiiat all operations requested to be done by 
components on the managed resource adhere to the 
ACID transactional properties. The resource manager 
thus must ensure tiiat all updates to the durable data by 
components tiiat are completed under a specific trans- 
action are made durable when tiie ti^nsaction commits, 
or are rolled back if the ti-ansaction aborts. The resource 
manager employs transaction-based synchronization 
protocols to isolate uncommitted work of active transac- 
tions. The resource manager also must ensure tiiread 
safety, which means the resource manager must be 
capable of being called by application components from 
any thread. The resource manager must further provide 
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logging and recovery so that transactions involving the 
resource are durable over crashes and other failures 
(comniunications failures, process failures, and storage 
medium failures, as well as server system failures). 
[0008] Further, an MTS Resource Manager (a 
resource manager that has been written to support 
MTS) must meet some additional requirements. In par- 
ticular, an MTS Resource Manager implements all (or a 
substantial subset) of the "OLE Transactions" inter- 
faces, which allow integration into MTS and interface to 
the MS DTC. Additionally, an MTS Resource Manager 
must provide a resource dispenser (a service that pro- 
vides pooling and automatic transaction enlistment for 
MTS server application components) for tiieir managed 
resource. If there is no Resource Dispenser, then an 
alternative mechanism for automatic transaction enlist- 
ment must be provided. 

[0009] Due to these difficulties, few resource manag- 
ers are yet available for MTS (the Microsoft SQL Server 
version 6.5 previously mentioned being one example). 
However, a wide variety of resources with no transac- 
tion support are cun'entiy available on the market, and 
deployed in use. Further, there are a variety of resource 
managers (herein referred to as legacy resource man- 
agers) for otiier transactional systems that don't provide 
the required interfaces (i.e., the OLE transactions inter- 
faces) to interoperate in MTS, such as to interface to the 
MS DTC. For example, a number of travel industry res- 
ervations systems have reservations databases man- 
aged under the IBM CICS transactional system. It is 
therefore desirable to integrate such non-transactional 
resources and legacy resource managers into MTS 
more easily than implementing an MTS resource man- 
ager specif ic to each. 

[0010] The present Invention provides a form of 
resource management (herein referred to as "compen- 
sation" or "compensating resource management") that 
allows durable resources to be more easily integrated 
into a transactional system, and particularly into a com- 
ponent-based on-line transaction processing applica- 
tion environment such as MTS. In compensating 
resource management, a durable resource is integrated 
to participate in transactions under the transactional 
system by providing a compensating action to reverse 
each normal action performed on the resource as part 
of a transaction. The normal action is persisted on ttie 
resource at tiie time of request. In a case where tiie 
transaction aborts, the compensating action is invoked 
outside of the transaction to return tiie durable resource 
to its pre-transaction state. For durability, information 
iderrtifying the compensating action to be taken for each 
normal action performed during a fransaction is written 
to a log on a write-ahead basis. Thus, in the case of a 
failure, recovery can be performed in accordance with 
the status of tiie transaction. 
[0011] In a conrponent-based on-line transaction 
processing application environment such as MTS. com- 
pensating resource management can be provided for a 



particular durable resource by implementing a compen- 
sating resource manager (CRM). In the CRM. a devel- 
oper implements a compensating action for each 
normal action that the CRM supports on tiie durable 
5 resource. The developer also implements the CRM to 
perform write-ahead logging in connection with each 
normal action to specify tiie compensating action for 
that normal action. 

[0012] In accordance with one embodiment of tiie 
10 invention illustrated herein (the illustrated embodiment), 
tiie CRM is developed as a pair of components, a CRM 
worker and a CRM compensator which share state (i.e., 
data) only through the medium of the log. The CRM 
worker performs the normal action at the time of request 
15 by a server application as a part of a transaction for tiie 
server application. This action and an interface ttirough 
which tiie action is accessed by tiie server application 
are specific to the particular CRM. When the server 
application invokes the normal action via the interface, 
20 the CRM worker also writes a log record to a system- 
provided log which identifies the CRM compensator. 
[P013] The CRM compensator implements tiie com- 
pensating action corresponding to tiie CRM worker's 
normal action. The CRM conrpensator that was desig- 
ns nated by the CRM worker is later created to participate 
in later phases of the two phase commit protocol (e.g.. 
Phase 1 and Phase 2) by taking appropriate further 
actions in relation to the normal action logged by tiie 
CRM worker. The CRM compensator supports a sys- 
30 tem-defined interface by which it receives two phase 
commit protocol notifications (e.g., prepare, commit and 
abort notifications) from the ti'ansaction manager (by 
way of a log recovery manager in the illusti'ated embod- 
iment). These notifications altow tiie CRM compensator 
35 to participate in these phases of the two phase commit 
protocol. 

[0014] More specifically, during the prepare phase) 
the CRM compensator can vote against committal of 
the transaction and force an abort in response to tiie 

40 prepare notification (e.g., by returning a value to vote 
"No" In response to the prepare notification). The com- 
mit notification affords tiie CRM compensator an oppor- 
tunity to perform clean-up processing after the normal 
action of the CRM worker. This clean-up processing is 

46 tiie removal of any state (durable or non-durable) ttiat is 
being maintained for purposes of compensating for an 
aborted transaction. The commit notification also 
affords the compensator the opportunity to do any work 
that is irreversible. For example, in an ATM ti'ansaction, 

so an account balance may be debited and cash dis- 
pensed. It is undesirable to dispense cash unless tiie 
debit is guaranteed to occur. Witfi a CRM tiiat manages 
the ATM. a CRM compensator would vote "yes" in 
response to a prepare notification as long as there is 

55 physically enough cash in tiie ATM. Then, in response 
to tiie commit notification, the CRM compensator 
causes the ATM to actually dispense tiie cash. In 
response to the abort notification, the CRM oompensa- 
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tor performs the compensating action to reverse the 
CRM worker's normal action. Accordingly, during nor- 
mal processing of a transaction, the CRM compensator 
participates in the transaction prepare phase, and is 
notified of the transaction outcome. The CRM compen- 
sator can then clean up on commit, or compensate on 
abort. During recovery, on the other hand, the CRM 
compensator is again created and informed of the trans- 
action's outcome based on the log, allowing the CRM 
compensator to complete transaction processing (as 
appropriate) involving the resource as If there had not 
been a failure. For example, if Phase 1 was not com- 
plete before a system aash. the transaction is aborted 
and the CRM compensator is delivered an abort notifi- 
cation. 

[0015] In the embodiment illustrated herein, each 
action (defined as the work done during a transaction, 
or set of log records) implemented by the CRM compen- 
sator, including particularly the compensating action, 
must be idempotent. This means that the CRM compen- 
sator's action on a commit or abort of the transaction 
can be attempted any number of times, and If the action 
ever succeeds, the action achieves the same result as if 
the action had succeeded on its first attempt. 
[0016] Additional features and advantages of the 
invention will be made apparent from the following 
detailed description of an illustrated embodiment which 
proceeds with reference to tiie accompanying drawings. 

BRIEF DESCRIPTION OF THE DRAWINGS 

[0017] 

Figure 1 is a block diagram of a distributed compu- 
ter system tiiat may be used to implement a method 
and apparatus embodying the invention tor com- 
pensating resource management in an on-line 
transaction processing system. 
Figure 2 is a block diagram of a server application 
execution environment with services for transaction 
processing with compensating resource manage- 
ment according to the illustrated embodiment of the 
invention. 

Figure 3 is a block diagram of a component-based 
architecture of a compensating resource manager 
(CRM) operable in the server application execution 
environment of Figure 2 to provide compensating 
resource management according to tiie illustrated 
embodiment of the invention. 
Figure 4 is a flow diagram of an order of execution 
within the CRM architecture of Figure 3. 
Figure 5 is a flow diagram of a logging process per- 
formed by a CRM worker component in tiie archi- 
tecture of Figure 3. 

Figure 6 is a program listing of an "ICrmLogContror 
interfiace on a CRM clerk in the compensating 
resource manager architecture of Figure 3. 
Figure 7 is a program listing of data structures for 



an "ICrmCompensator" interface of a CRM com- 
pensator in tiie compensating resource manager 
architecture of Figure 3. 

Figure 8 is a program listing of an "ICrmCompensa- 
5 torVariants" intertece of the CRM conpensator in 
the compensating resource manager architecture 
of Figure 3. 

Rgure 9 is a program listing of an "ICrmCompensa- 
tor" interface of the CRM compensator in the com- 
10 pensating resource manager architecture of Figure 
3. 

Figure 10 is a program listing of an "ILogReoover" 
interface of a recovery engine in the compensating 
resource manager architecture of Figure 3. 
15 Figure 11 is a program listing of an ILogRecover- 
Clerk" interface of a CRM recovery clerk and the 
CRM derk in the compensating resource manager 
architecture of Rgure 3. 

Rgure 12 is a program listing of an "ILogRecover- 
20 ClerkPhaseNotification" interface of tiie CRM 
recovery clerk and the CRM clerk in the compen- 
sating resource manager architecture of Rgure 3. 
Rgure 13. is a program listing of an "ILogRecover- 
ClerkRegistration* interface of the recovery engine 
25 in the compensating resource manager architec- 
ture of Figure 3. 

Rgure 14 is a program listing of an ILog" interface 
of a log object for a persistent log in tiie compensat- 
ing resource manager architecture of Rgure 3. 

30 Rgure 1 5 is a program listing of an "ICrmFormatLo- 
g Records" interface in tiie compensating resource 
manager architecture of Figure 3. 
Rgure 1 6 is a program listing of an ICrmMonitorLx)- 
gRecords** interface of the CRM derk in the oom- 

35 pensating resource manager architecture of Rgure 
3. 

Figure 17 is a program listing of an "ICrmMonitor- 
Clerks** interface of a clerks collection object in tiie 
compensating resource nianager architecture. 
40 Rgure 18 is a program listing of an "ICrmMonitor" 
interface" of the CRM recovery clerk in the compen- 
sating resource manager architecture of Rgure 3. 

DETAILED DESCRIPTION OF THE ILLUSTRATED 
45 EMBODIMENTS 

[001 8] The present invention is directed toward meth- 
ods, systems, and software products for compensating 
resource management in on-line transaction process- 

50 ing. In one embodiment illustrated herein, the invention 
is incorporated into operating software for server appli- 
cations on distributed computing systems, entitied 
''COM+" which is part of the "Microsoft Windows NT 
Server 5.0" operating system by Microsoft Corporation 

55 of Redmond, Washington. Briefly described, this soft- 
ware provides a component framework and run-time 
execution environment for server applications that, 
among other things, includes system services to sup- 
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port transaction processing using a two phase commit 
protocol on distributed computing systems. 

Exemplary Operating Environmern 

[0019] Figure 1 and the following discussion are 
Intended to provide a brief, general description of a suit- 
able computing environment in which the invention may 
be implemented. While the invention will be described in 
the general context of computer-executable instructions 
of a computer program that runs on a server computer, 
those skilled in the art will recognize that the invention 
also may be implemented in combination with other pro- 
gram modules. Generally, program modules include 
routines, programs, components, data structures, etc. 
that perform particular tasks or implement particular 
abstract data types. Moreover, those skilled in the art 
will appreciate that the Invention may be practiced with 
other computer system configurations, including single- 
or multiprocessor computer systems, minicomputers, 
mainframe computers, as well as personal computers, 
hand-held conrputing devices, microprocessor-based or 
programmable consumer electronics, and the like. The 
illustrated embodiment of the invention also is practiced 
in distributed computing environments where tasks are 
performed by remote processing devices that are linked 
through a communications network. But. some embodi- 
ments of the invention can be practiced on stand-alone 
computers. In a distributed computing environment 
program modules may be located in both local and 
remote memory storage devices. 
[0020] With reference to Figure 1 , an exemplary sys- 
tem for implementing the invention includes a conven- 
tional server computer 20, including a processing unit 
21 , a system memory 22. and a system bus 23 that cou- 
ples various system components including the system 
memory to the processing unit 21. The processing unit 
may be any of various commercially available proces- 
sors, including Intel x86. Pentium and compatible micro- 
processors from Intel and otiiers, including Cyrix, AMD 
and Nexgen; Alpha from Digital: MIPS from MIPS Tech- 
nology, NEC, IDT, Siemens, and others; and the Pow- 
erPC from IBM and Motorola. Dual microprocessors 
and otiier multi-processor architectures also can be 
used as the processing unit 21 . 
[0021 ] TTie system bus may be any of several types of 
bus structure including a memory bus or menrwry con- 
troller, a peripheral bus, and a local bus using any of a 
variety of conventional bus architectures such as PCI, 
VESA, MicroChannel, ISA and EISA, to name a few. The 
system memory includes read only memory (ROM) 24 
and random access memory (RAM) 25. A basic 
input/output system (BIOS), containing the basic rou- 
tines that help to transfer information between elements 
within tiie server computer 20, such as during start-up, 
is stored in ROM 24. 

[0022] The server computer 20 further includes a hard 
disk drive 27. a magnetic disk drive 28, e.g., to read 



from or write to a removable disk 29, and an optical dfsk 
drive 30, e.g., for reading a CD-ROM disk 31 or to read 
from or write to otiier optical media. The hard disk drive 
27, magnetic disk drive 28. and optical disk drive 30 are 
connected to the system bus 23 by a hard disk drive 
interface 32, a magnetic disk drive interface 33. and an 
optical drive interface 34, respectively. The drives and 
their associated computer-readable media provide non- 
volatile storage of data, data structures, computer-exe- 
cutable insti'uctions. etc. for tiie server computer 20. 
Although the description of computer-readable media 
above refers to a hard disk, a removable magnetic disk 
and a CD, it should be appreciated by those skilled in 
the art tiiat other types of media which are readable by 
a computer, such as magnetic cassettes, flash memory 
cards, digital video disks. Bernoulli cartridges, and the 
like, may also be used in tiie exemplary operating envi- 
ronment. 

[0023] A number of program modules may be stored 
in the drives and RAM 25, including an operating sys- 
tem 35, one or more application programs 36, other pro- 
gram modules 37, and program data 38. The operating 
system 35 in the illustrated sender computer is tiie 
Microsoft Windows NT Sender operating system, 
together witii tiie before mentioned Microsoft Transac- 
tion Server. 

[0024] A user may errter commands and information 
into tiie server computer 20 tiirough a keyboard 40 and 
pointing device, such as a mouse 42. Otiier input 
devices (not shown) may include a microphone, joy- 
stick, game pad, satellite dish, scanner, or tiie like. 
These and otiier input devices are often connected to 
the processing unit 21 tiirough a serial port interface 46 
tiiat is coupled to tiie system bus, but may be connected 
by other interfaces, such as a parallel port, game port or 
a universal serial bus (USB). A monitor 47 or other type 
of display device is also connected to the system bus 23 
via an interface, such as a video adapter 48. In addition 
to the monitor, server computers typically include otiier 
peripheral output devices (not shown), such as speak- 
ers and printers. 

[0025] The server conputer 20 may operate in a net- 
worked environment using logical connections to one or 
more remote computers, such as a remote client com- 
puter 49. The remote computer 49 may be a worksta- 
tion, a server computer, a router, a peer device or other 
common network node, and typically includes many or 
all of the elements described relative to the server com- 
puter 20, although only a memory storage device 50 
has been illustrated in Figure 1. The logical connections 
depicted in Figure 1 include a local area network (LAN) 
51 and a wide area network (WAN) 52. Such networking 
environments are commonplace in offices, enterprise- 
wide computer networks, intranets and the Internet. 
[0026] When used in a LAN networking environment, 
tiie server computer 20 is connected to the local net- 
work 51 tiirough a network interlace or adapter 53. 
When used in a WAN networking environment, tiie 
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server computer 20 typically includes a rrKxiem 54, or Is 
connected to a communications server on the LAN. or 
has other means for establishing communications over 
the wide area network 52. such as the Internet. TTie 
modem 54, which may be internal or external, is con- 
nected to the system bus 23 via the serial port interlace 
46. In a networked environment, program modules 
depicted relative to the server computer 20, or portions 
thereof, may be stored in the remote memory storage 
device. It will be appreciated that the network connec- 
tions shown are exemplary and other means of estab- 
lishing a communications link between the computers 
may be used. 

[0027] In accordance with the practices of persons 
skilled in the art of computer programming, the present 
invention is described below with reference to acts and 
symbolic representations of operations that are per- 
formed by the server computer 20, unless indicated oth- 
enwise. Such acts and operations are sometimes 
referred to as being computer-executed. It will be appre- 
ciated that the acts and symbolically represented oper- 
ations include the manipulation by the processing unit 
21 of electrical signals representing data bits which 
causes a resulting transformation or reduction of the 
electrical signal representation, and the maintenance of 
data bits at memory locations in the memory system 
(including the system memory 22, hard drive 27, floppy 
disks 29. and CD-ROM 31) to thereby reconfigure or 
othenwise alter the computer system's operation, as well 
as other processing of signals. The memory locations 
where data bits are maintained are physical locations 
that have particular electrical, magnetic, or optical prop- 
erties corresponding to the data bits. 

Overview Qf TTie MTS Programming ModA 

[0028] Figure 2 depicts a server application execution 
environment 82 of the Microsoft Transaction Sender 
(MTS) in which compensating resource management 
according to the invention is incorporated. The MTS 
execution environment 82 is described in more detail in 
the above incorporated MTS Patent Applications. 
[0029] With reference now to Figure 2, a transaction 
server executive 80 provides run-time or system serv- 
ices to aeate the run-time execution environment 80 
that supports on-line transaction processing by server 
application components (e.g., server application com- 
ponent 86) on a server computer 84. The transaction 
server executive 80 also provides services for thread 
and context management to the server application com- 
ponents 86. Additionally, the transaction server execu- 
tive 80 provides system-defined objects (including a 
component context object 136) that support component 
integration Interfaces. The illustrated transaction server 
executive 80 is implemented as a dynamic link library 
("DLL"). (A DLL is a well-known executable file format 
which allows dynamic or run-time linking of executable 
code Into an application program's process.) The trans- 



action server executive 80 is loaded directly into appli- 
cation server processes (e.g.. "ASP" 90) that host 
server application components, and runs transparently 
in the background of these processes. 

5 [0030] The illustrated ASP 90 is a system process that 
hosts execution of server application components. Each 
ASP 90 can host multiple server application compo- 
nents that are grouped into a collection called a "pack- 
age." Also, multiple ASPs 90 can execute on tiie server 

10 computer under a multi-threaded, multi-tasking operat- 
ing system (e.g., Microsoft Windows NT in the illus- 
trated embodiment). Each ASP 90 provides a separate 
trust boundary and fault isolation domain for the server 
application components. In other words, when run in 

15 separate ASPs, a fault by one sen/er application com- 
ponent which causes its ASP to terminate generally 
does not affect tiie server application conrponents in 
another ASP. In the illustrated embodiment, server 
application components are grouped as a package to 

20 be run together in one ASP 90 using an administration 
utility called "the COM Explorer." This utility provides a 
graphical user interface for managing attributes associ- 
ated with server application components, including 
grouping ttie components into packages. 

25 [0031] In a typical Installation shown in Figure 2. the 
execution environment 80 is on the server computer 84 
(which may be an example of the computer 20 
described above) that is connected in a distributed com- 
puter network comprising a large number of client com- 

30 puters 92 which access the server application 
components in tiie execution environment. Alternatively, 
the execution environment 80 may reside on a single 
computer and host server application components 
accessed by client processes also reskJent on that com- 

35 puter. 

[0032] The server application components 86 that are 
hosted in the execution environment 80 of the ASP 90 
implement tiie business logic of a sender application, 
such as the code to manage class registrations in a uni- 

40 varsity's registration application or orders in an on-line 
sales application. Typically, each server application 
comprises multiple components, each of which contains 
program code for a portion of the application's work. For 
example, a banking application may comprise a transfer 

45 component, a debit account component, and a credit 
account component which perform parts of the work of 
a money transfer operation in the application. The debit 
account component in tiiis banking application example 
implements program code to debit a specified account 

50 in a banking database by a specified amount. The credit 
account component implements program code to aedit 
a specified account in tiie database by a specified 
amount. The transfer component implements program 
code that uses tiie debit account component and credit 

55 account conponent to effect a money transfer between 
two accounts. 

[0033] The server application component 86 in tiie 
illustrated embodiment contomns to the Component 
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Object Model ("COM**) of Microsoft Corporation's OLE 
and ActiveX specifications (i.e.. is implemented as a 
"COM Object"), but alternatively may be implemented 
according to other object standards including the 
CORBA (Common Object Request Broker Architecture) 
specification of the Object Management Group. OLE's 
COM specification defines binary standards for compo- 
nents and their interfaces which facilitate the integration 
of software components. By convention, the interfaces 
of a COM object are illustrated graphically as a plug-in 
jack as shown for the server application component 86 
in Rgure 2. Also, interfaces conventionally are given 
names beginning with a capital "I." For a detailed dis- 
cussion of OLE. see Kraig Brockschmidt. Inside OLE, 
Second Edition, Microsoft Press, Redmond. Washing- 
ton. 1995. 

[0034] In tiie execution environment 80 of Figure 2. 
the sender application component 86 is executed under 
control of the transaction server executive 80 in the ASP 
90. The transaction server executive 80 is responsible 
for loading the server application DLL 300 into the ASP 
90 and instantiating the server application component 
86 using tiie dass factory 122. The transaction server 
executive 80 further manages calls to the server appli- 
cation component 86 from client programs (whether 
resident on the same computer or over a network con- 
nection). 

[0035] TTie illustrated execution environment 80 
imposes certain additional requirements on the server 
application component 86 beyond conforming with 
COM requirements. First, the server application compo- 
nent is implemented in a DLL file (i.e., the server appli- 
cation DLL 120 of Figure 3). (COM objects otiierwise 
alternatively can be implemented in an executable 
f .exe") file.) Second, tfie component's DLL file 120 has 
a standard class factory 122 (i.e.. the DLL implements 
and exports tiie DIIGetClassObject method, and sup- 
ports the ICIassFactory interface). Third, tiie server 
application component exports only interfaces that can 
be standard marshaled, meaning tiie component's 
interfaces are either described by a type library or have 
a proxy-stub DLL The proxy-stub DLL provides a proxy 
component 130 in a client process 132 on the client 
computer 92. and a stub component 131 in the ASP 90 
on the server computer 84. The proxy component 130 
and stub component 131 marshal calls from a client pro- 
gram 134 across to the server computer 84. The proxy- 
stub DLL in the illustrated system is built using tiie MIDL 
version 3.00.44 provided with the Microsoft Win32 SDK 
for Microsoft Windows NT 4.0 with the Oicf compiler 
switch, and linked with the toBnsaction server executive 
80. These additional requirements conform to well 
known practices. 

[0036] The client program 134 of the server applica- 
tion component 86 is a program tiiat uses the server 
application component. The client program can be pro- 
gram code (e.g.. an application program. COM Object, 
etc.) that runs outside the execution environment 80 



(out of tiie control of tiie transaction server executive 
80). Such client programs are refen-ed to as l^ase cli- 
ents." Alternatively, the client program 134 can be 
another server application component that also runs 

5 under control of the transaction server executive (either 
in the same or a separate ASP 90). The client program 
134 can reside on the server computer 84 or on a sepa- 
rate client computer 92 as shown in Figure 2 (in which 
case the client computer interacts with tiie server appli- 

10 cation component 86 remotely through the proxy object 
130 and stub object 131). 

[0037] The server computer 84 also runs a resource 
manager 140 and a resource dispenser 144. The 
resource manager 140 is a system service that man- 

15 ages durable data (e.g.. data In a database 146). The 
server application component 86 can use the resource 
manager to niaintaln the durable state of tiie server 
application (such as, the record of inventory on hand, 
pending orders, and accounts receivable in an on-line 

20 sales server application). Examples of resource manag- 
ers in the illustrated embodiment include tiie Microsoft 
SQL Senrer. durable message queues, and transac- 
tional file systems. Preferat)ly. the resource manager 
140 supports performing changes or updates by tiie 

25 server application component 86 to tiie server applica- 
tion's durable state on a ti^ansactional basis (i.e., in 
transactions conforming to tiie well-known ACID proper- 
ties). 

[0038] The resource dispenser 144 is a service tiiat 

30 manages non-durable shared state (i a, without tiie 
guarantee of durability) on behalf of the server applica- 
tion components witiiin the ASP 90. Resource dispens- 
ers also are responsible for automatic fansaction 
enlistment in tiie illustrated execution environmerrt. as 

35 described in the above incorporated MTS Patent Appli- 
cations. Examples of tiie resource dispenser 144 in tiie 
illustrated embodiment include an ODBC resource dis- 
penser tiiat maintains a pool of database connections 
conforming to the Microsoft Open Database Connectiv- 

40 ity ("ODBC") call level interface. The ODBC resource 
dispenser allocates database connections to tiie server 
application component for accessing data from a data- 
base 146 (generally, through its resource manager 
140). Also, tiie ODBC resource dispenser reclaims 

45 database connections when released by ttie server 
application components fbr later reuse. 
[0039] The illustrated execution environment 82 fur- 
ther includes a ti'ansaction manager 148. The transac- 
tion manger 148 is a system service that coordinates 

so transactions that span multiple resource managers, 
including where the resource managers reside on more 
tiian one server computer in a distributed network. The 
transaction manager 148 ensures that updates across 
all resources managers involved in a transaction occur 

55 in conformance with the ACID properties using tiie well 
known two-phase commit protocol, regardless of fail- 
ures (e.g., computer or network hardware or software 
failures, or enors caused by a misbehaved resource 
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manager or application), race conditions (e.g., a trans- 
action that starts to commit while one resource man- 
ager initiates an abort), or availability (a resource 
manager prepares a transaction but never returns). The 
illustrated transaction manager 148 is the Microsoft Dis- 
tributed Transaction Coordinator (MSDTC) released as 
part of Microsoft SQL Server 6.5. 

Th^ qomp^nsgtinq Resource Mgnqqer Arghit^cture 

[0040] With reference now to Figure 3, a component 
or object-based architecture 200 of a compensating 
resource manager (CRM) includes a number of system- 
provided components and system-delined interfaces 
that allow developers to more rapidly and easily inte- 
grate resources with durable data storage into the MTS 
execution environment 82 (Fig 2), without having to 
implement a full resource manager and resource dis- 
penser specific to the resource (e.g.. resource manager 
140 and resource dispenser 144 of Fig 2). The illus- 
trated architecture 200 is particularly applicable to two 
resource scenarios, namely (1) a legacy or black box 
transaction processing system that has its own internal 
mechanism to deal with transactions but does not sup- 
port the OLE transactions interfaces, and (2) resources 
with no transactional support. The architecture 200 
allows easier integration into the MTS environment 82 
(Figure 2) in the former scenario by providing a 
resource manager infrastructure with support for the 
OLE transactions interfaces, and eliminating the neces- 
sity, of having a resource dispenser for the resource 
manager. Further, the architecture 200 allows the 
resources In each scenario to be integrated with a sim- 
pler, easier to develop resource manager through use of 
compensating resource management according to the 
invention. 

[0041] In the illustrated compensating resource man- 
ager architecture 200, the developer need implement 
only a CRM worker 202 and a CRM compensator 206 
that utilize the system-provided components and inter- 
faces of the architecture 200 to provide compensating 
resource management of the resource. The CRM 
worker 202 and CRM compensator 206 are compo- 
nents conforming to the COM object model. The CRM 
worker 202 and CRM compensator 206 typically are 
installed into an MTS library package so that they may 
be used in any MTS server process (e.g., ASP 90). 
[0042] In the CRM worker 202. the developer imple- 
ments logic (i.e., program code) specific to the resource 
to perform a normal action on the resource as part of a 
transaction. The developer also implements a resource- 
specific interface (e.g., the "IDoWork" interface 210) to 
which a server application component 86 can issue 
calls to cause the CRM worker 202 to perform the nor- 
mal action on the resource. The CRM worker 202 
enacts the normal action on the resource at the time of 
the server application component's request, such that 
the results of the normal action are persistent on the 



resource immediately after the request. 
[0043] On the other hand, the developer innplements 
logic in the CRM compensator 206 that provides com- 
pensating actions related to the normal action of the 

5 CRM worker 202. The developer further implements the 
CRM compensator 206 to support a system-defined 
interface (the ICompensatingResourceManager** inter- 
face 212) by which the CRM compensator receives pre- 
pare, commit and abort notifications from the 

10 transaction manager 148 (Figure 2). These notifications 
from the transaction manager are delivered to the CRM 
compensator by way of system-provided infrastructure, 
a recovery engine and a CRM clerk described below. 
During the prepare phase of a transaction in which the 

15 CRM worker 202 has performed its normal action, the 
CRM compensator can cause the transaction to abort in 
response to the prepare notification, such as where cir- 
cumstances would prevent successful completion of the 
transaction. In the second phase of the transaction, the 

20 CRM compensator can respond to a commit notification 
by performing dean-up actions appropriate to the nor- 
mal action of the CRM worker on the resource. Alterna- 
tively, the CRM compensator can respond to an abort 
notification by performing a compensating action that 

25 reverses the normal action of the CRM worker. 

[0044] The normal, clean-up and compensating 
actions of the CRM worker and compensator generally 
vary depending on the specific durable resource being 
managed. Where tiie resource is a file system or data- 

30 base for example, the actions can include data process- 
ing activities, such as modifying data, writing new data, 
or deleting data from tiie resource. In the case of some 
resources, the CRM compensator's clean-up and/or 
compensating actions can include activities In addition 

35 to data processing, such as dispensing cash, tickets, or 
other items from an ATM or other automated dispensing 
machine, which may have irreversible real-world results 
(such operation having irreversible physical world con- 
sequences being referred to herein as "real opera- 

40 tions"). 

[0045] Additional components of ttie CRM architec- 
ture 200 are incorporated into the MTS run-time envi- 
ronment and services, and are thus "system-provided.** 
This allows the developer to implement only the CRM 

45 worker and CRM compensator tiiat are specific to a par- 
ticular resource, and rely on these system-provided 
components to provide services to deal witii issues 
such as logging, recovery, and thread safety. The sys- 
tem-provided components of the illustrated architecture 

50 200 include a CRM clerk 222, a CRM recovery clerk 
224, and a persistent log 226. Each of these also are 
implemented as COM conrponents. All of these compo- 
nents are run witiiin the application server process 
(ASP) 90 (also shown in Figure 2). 

55 [0046] The CRM architecture 200 provides tiiread 
safety in that the system-provided components of the 
architecture are individually thread safe, meaning they 
can be called from any thread. Furtiier, the CRM archi- 
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tecture 200 supports all of the OLE transactions inter- 
faces required to interface with' MIS. The CRM 
architecture 200 does not assume that the consumers 
of the architecture's functionality (i.e., the server appli- 
cation components 86) are themselves thread safe. The 5 
CRM architecture 200 guarantees to make all calls into 
the CRM compensator in the same apartment in which 
the CRM compensator was created according to stand- 
ard COM programming practices. In other words, the 
CRM architecture assumes that its consumers are at 
least apartment model components (a well known 
threading model). 

[0047] The CRM clerk 222 and CRM recovery clerk 
224 provide logging and recovery services in the archi- 
tecture 200. During normal operation, each CRM 
worker 202 will create Its own instance of a CRM clerk 
(i.e.. there is a one-to-one relationship of CRM worker to 
CRM clerk). The CRM worker 202 accesses the CRM 
clerk 222 through a system-defined interface, the ICrm- 
LogControl interface 230. to queue information that is to 
be logged in the persistent log 226. The CRM derk will 
add additional information to the log records before they 
are written to the k)g. During normal processing, the 
CRM clerk 222 also is responsible for Instantiating the 
CRM compensator and passing two phase commit noti- 
fications to the CRM compensator, as needed. 
[0048] The CRM recovery clerk 224 operates as a log 
and recovery manager, that is common to all compen- 
sating resource managers on the computer system. The 
CRM recovery clerk 224 is a singleton COM compo- 
nent, meaning there is only ever one instance of the 
CRM recovery clerk in the ASP 90. The CRM recovery 
clerk 224 performs the initial recovery on the persistent 
log 226. which is automatically Initiated when the MTS 
server process (e.g., ASP 90) that hosts the CRM com- 
ponents starts up. Thereafter, the CRM recovery clerk 
224 remains active to initiate checkpoints on the log, 
and to provkie a central point through which CRM clerks 
are monitored. 

[0049] The CRM recovery clerk 224 supports an 
"ICrmMonitor" interface 234, which is obtained by call- 
ing the "CoCreatelnstanceO" API metiiod with the CRM 
recovery clerk's CLSID. The ICrmMonltor" Interface is 
defined in \he program listing 320 shown in Figure 1 8. 
The "ICrmMonitor'* interface 234 is used to nrK)nitor 
which transactions are currently in-progress for the 
CRMs in the ASP 90 (such as by a program or COM 
component tiiat provides user displays or dialogs for a 
human operator or administrator). The text descriptions 
provkJed by the CRM worker when registering the CRM 
compensator (see the "RegisterCompensatorQ" 
method described below) are available to akl in search- 
ing for a particular CRM activity. 
[0050] The "ICrmMonitor" interface provides a metiiod 
("GetClerksO") to obtain an interface pointer to an 
ICrmMonitorClerks" interface on a clerks collection 
object that tracks the CRM clerks 222 of the compensat- 
ing resource manager architecture 200. The ICrmMon- 



itorClerks'' interface is defined in the program listing 319 
shown in Figure 17. Through tiiis Interface, a pointer to 
an "ICrmMonitorLogRecords" interface supported on 
the CRM clerk 222 can be obtained. The "ICrmMonitor- 
LogRecords** interface is used to monitor the individual 
log records maintained by a specifk; CRM clerk for a 
given transaction, such as for human recovery 
described below. The "ICrmMonitorl-og Records" is 
defined in the program listing 318 shown in Figure 16. 
[0051] Each ASP 90 that uses the CRM will have its 
own associated persistent log 226 to store log records. 
The persistent log 226 in the illustrated CRM architec- 
ture 200 is a TXF format log file, which has a file name 
based on tiie AppkJ associated witfi the ASP 90. When 
writing log records (in response to the "ForceLogQ" 
metiiod described below), tiie CRM clerk 222 writes log 
records in a sequential order Into the persistent log 226. 
The CRM recovery clerk 224 also periodically initiates 
check points in the persistent log 226 to reclaim space 
from log records freed after completed transactions. 
[0052] The CRM worker 202 logs sufficient informa- 
tion Into the persistent log 226 (through the CRM clerk 
222 and CRM recovery clerk 224. as just described) 
typically, but not necessarily, on a write-ahead basis as 
it performs its normal action to the resource on behalf of 
the server application component 86, so that the CRM 
architecture 200 can cause the CRM compensator 206 
to take appropriate actions in response to the two phase 
commit protocol notifications (e.g., a vote action during 
prepare, clean-up action on commit, or compensating 
action on abort). The CRM worker 202 also registers a 
class identifier ("CLSID") of the CRM compensator 206 
with tiie CRM clerk 222. Later, when tiie transaction is 
over (which in the MTS environment is typically in 
response to a SetCompIete or SetAbort call from tiie 
server application component(s) 86 in the t-ansaction. 
as described in tiie above incorporated MTS Patent 
Applications), the CRM derk 222 aeates the CRM 
compensator 206 and calls appropriate methods on its 
ICrmCompensator (or ICrmCompensatorVariants) Inter- 
face 212 for each of the two phase commit notifications 
tiiat it receives from the transaction manager 148 (Fig- 
ure 2). Witii the two phase commit notifications, the 
CRM clerk 222 delivers individually the log records writ- 
ten by the CRM worker 202 for the transaction - in a for- 
ward order for commit and reverse order for abort to 
preserve the ordering of actions witiiin the transaction. 
The CRM compensator 206 also can log information of 
its own compensating actions to the persistent log that 
may be needed during recovery. The CRM worker 202 
and the CRM compensator 206 tiius share state only 
tiirough the persistent log 226. 
[0053] The persistent log 226 in the illustrated archi- 
tecture 200 is implemented as a log object 240, a recov- 
ery engine 242, and a log file 244. The log object 240 is 
a COM object tiiat encapsulates a serial stream of log 
records, and Is responsible for stably writing a sequen- 
tial stream of log records into the log file 244. The log 
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object 240 provides methods for writing and reading the 
log records from the log file 244 through an "ILog** inter- 
face 246, which are used by the CRM clerk 222. the 
CRM recovery clerk 224 and the recovery engine 242. 
[0054] The log file 244 is a serial data stream stored s 
in non-volatile memory (e.g., on the hard drive 27 in Fig- 
ure 1 ), such as a file or collection of files of a file system, 
in which log records are stored. The illustrated log file 
244 is a file having the Microsoft TXF file format. Each 
log record In the illustrated log file 244 is kjentified by a 
log sequence number (LSN). which are monotonically 
increasing 64-bit integers in the serial stream. A sepa- 
rate log file is kept for each ASP 90 on tiie computer 20 
(Figure 1). In the illustrated architecture 200, the log file 
244 is identified by a file name based on an unique iden- 
tifier assodated with ttie respective ASP 90 (e.g.. the 
"Appid" in the Microsoft Windows NT operating system), 
and resides on a same file system path as a log of the 
transaction manager 148. This facilitates recovery 
based on the log. 

[0055] The recovery engine 242 is a COM object tiiat 
provides services through an "ILogRecover" Interface 
248 and ILogRecoverClerkRegistration" Interface for 
processing tiie log records from the log file 244 follow- 
ing a system restart according to a log recovery protocol 
to effect recovery from failures. The recovery process- 
ing implemented in the illustrated recovery engine 242 
is based on tiie well known ARIES log recovery proto- 
col, altiiough another log recovery protocol or a varia- 
tion thereof can instead be used. (See. C. Mohan, D. 
Haderle, B. Lindsay, H. Pirahesh and P. Schwarz, 
ARIES: A Transaction Recovery Method Supporting 
Fine-Granularity Locking and Partial Rollbacks Using 
Write-Ahead Logging, In Readings In Database Sys- 
tems, Second Edition (Michael Stonebraker ed. 1994).) 
The CRM recovery derk 224 and CRM clerk 222 regis- 
ter with the recovery engine 242 so that log records writ- 
ten by these entities can be provided by the recovery 
engine 242 during recovery. The recovery engine 242 
also enlists witii the transaction manager 1 48 (Figure 2) 
on the ti'ansaction In which the CRM worker 202 and 
CRM clerk 222 participate. During normal operation in 
the architecture 200, the recovery engine 242 receives 
the two phase commit notifications from the transaction 
manager 148 and passes the notifications along with 
log records reliating to tiie transaction to tiie CRM clerk 
222, which acts on the notifications by creating tiie CRM 
compensator 206 and initiating the appropriate com- 
pensating actions by the CRM compensator 206. The 
recovery engine 242 enlists on transactions with the 
transaction manager 148, and receives two phase com- 
mit notifications from the transaction manager using the 
OLE transactions interfaces. The CRM derk 222 and 
CRM recovery clerk 224 implement a set of interfaces 
(including "ILogRecoverClerk," ILogRecoverCler- 
kRecordsOnTerminate," and "ILogRecoverClerkPhase- 
Notrfication" interfaces) on which the clerks receive the 
two phase commit notifications from the recovery 



engine 242. 
Operating Sequence 

[0056] Figure 4 depicts an order of execution of tiie 
components witiiin the illustrated CRM architecture 
200. Initially, tiie server application component 86 cre- 
ates the CRM worker 202 using conventional COM 
object instantiation methodology as indicated at step 
251 . In a case where tiie server application component 
86 has a transaction, the MTS execution environment 
82 will automatically associate the CRM worker 202 in 
tiiat transaction as described in "Automatic Transaction 
Processing Of Component-Based Sewer Applications.** 
U.S. Patent Application Serial No. 08/959.141 (incorpo- 
rated herein above by reference). 
[0057] At a next step 252, tiie CRM worker 202 cre- 
ates an instance of the CRM derk 222 and obtains an 
interface reference to the ICrmLogConf ol interface 230 
of the CRM clerk 222 by calling the "CreatelnstanceQ" 
metiiod (a well known application programming inter- 
face (API) metiiod In the COM run-time services library 
used for object Instantiation) and specifying the CLSID 
of the CRM clerk and IID of tiie ICrmLogContrd Inter- 
face. This also automatically associates the CRM clerk 
instance in the transaction. 

[0058] After obtaining the ICrmLogConti-ol interface 
reference, the CRM worker 202 calls a "RegisterCom- 
pensatorO" metiiod of the interface to register the coun- 
terpart CRM compensator 206 for the CRM worker 202 
witfi the CRM clerk 222 as shown at step 253. The CRM 
worker 202 registers the CRM compensator 206 by an 
kientifier of its class (e.g., a program identifier 
(PROQID) or a class Identifier (CLSID)), which under 
COM provides sufficient identification for tiie CRM clerk 
222 to later aeate the CRM compensator 206. 
[0059] In addition, the CRM derk 222 registers itself 
witti the CRM recovery clerk 224 and tiie recovery 
engine 242 using a globally unkijue Identifier (QUID) 
associated with tiie specific instance of tiie CRM clerk 
dass. The CRM recovery derk 224 logs any active 
CRM clerks witii the log 226 to enable later reaeating 
tiie CRM clerk at recovery When tiie CRM clerk is reg- 
istered with the recovery engine 242. tiie recovery 
engine 242 enlists with tiie ta-ansactipn mariager 148 on 
tiie server application component's transaction. This 
allows the recovery engine 242 to receive two phase 
commit notifications issued by tiie ti'ansaction manager 
in the transaction, and pass the notifications to the CRM 
derk 222. 

[0060] At a next step 254, the server application com- 
ponent 86 requests that the CRM worker 202 perform 
work on the resource as part of its transaction. As the 
CRM worker 202 performs the requested work (i.e., its 
normal action), the CRM worker first logs sufficient 
information at step 255 to tiie persistent log 226 using 
tiie CRM clerk 222 for tiie CRM compensator to be able 
to take appropriate clean-up and compensating actions. 
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As explained below, the CRM worker 202 writes a 
sequence of log records to the CRM derk 222 (using 
the "WriteLogRecordO" or "WrUeLogRecordVariantsO" 
methods), and then causes the records to be written out 
to the persistent log on the write-ahead basis before 5 
performing the requested work (using the TorceLogQ" 
method). 

[0061 1 Later, at step 256, the transaction manager 1 48 
issues two phase commit protocol notifications to partic- 
ipants in the transaction (i.e.. components enlisted in 10 
the transaction). Including to the recovery engine 242 
which passes the notifications to the CRM clerk 222 
along with the log records previously written by the 
CRM worker 202. Typically, these notifications are sent 
after the server application component 86 that initiated is 
the transaction has called SetComplete to indicate that 
all work in the transaction is complete, or a component 
in the transaction calls SetAbort indicating the work 
cannot be successfully completed. SetComplete and 
SetAbort are interface methods of the system-provided 20 
context object 136 (Figure 2), and described in more 
detail in the above incorporated MIS Patent Applica- 
tions. The transaction manager 148 issues the two 
phase commit protocol notifications to the recovery 
engine 242 on the ITransaction ResourceAsync interface 25 
238 (which Is part of the OLE transactions interfaces). 
[0062] In response to each two phase commit protocol 
notification, the CRM clerk 222 at step 257 creates the 
CRM compensator 206 that was previously registered 
by the CRM worker 202 with the C RM clerk 222. At step 30 
258 the CRM clerk 222 then calls an appropriate 
method of the ICrmCompensator interface 212 to pass 
the notification and related log records to the CRM com- 
pensator 206. With Its call to the CRM compensator 
206, the CRM clerk 222 passes an interface pointer for 35 
the ICrmLogControl interlace 230 to allow the CRM 
compensator to write log recorc^ of its compensating 
actions. 

[0063] At step 259. the CRM compensator 206 per- 
forms the vote, clean-up or compensating action appro- 40 
priate to the two phase commit protocol notification 
based on the information logged by the CRM worker 
202. As appropriate, the CRM compensator 206 also 
may log information of Its dean-up or compensating 
actions for use during recovery. 4S 

Lo g gin g 

[0064] Figure 5 depicts a process 280 by which the 
CRM worker 202 logs information to compensate for its so 
normal action on the resource. IN the illustrated archi- 
tecture 200 (Figure 3), information is written to the log in 
a lazy write fashion. The CRM worker 202 uses the 
CRM clerk's ICrmLogControl interlace 230 to queue up 
log records that represent one action taken by the CRM 55 
worker, which are then forced together to the nonvolatile 
storage in the log file 244. The CRM worker 202 prefer- 
ably performs the logging on a write-ahead basis prior 



to executing any actions on the resource that may later 
require compensation. 

[0065] As an initial step 281 of the logging process 
280, the CRM worker 202 builds a log record as a col- 
lection of data elements. In tiie Illustrated architecture 
200, the log record can be structured or unstructured. A 
structured log record is a collection of Variant-type data 
elements, such as a Visual Basic collection object. 
Unstructured log records are simply a buffer of bytes. 
Typically, a CRM worker written in the Microsoft Visual 
Basic programming language will write structured log 
records, while one written in the Microsoft Visual Ch- or 
3++ languages writes unstructured log records. The 
CRM worker 202 in the illustrated compensating 
resource manager architecture 200 is not permitted to 
mix structured and unstructured log records, and must 
write log records of only one of these types. 
[0066] When the log record is built, the CRM worker 
202 at step 282 calls a "WriteLogRecordO" method (or 
"WriteLog Record VariantsO" method for structured log 
records) on tiie ICrmLogControl interlace 230 of the 
CRM clerk 222 to copy the log record into a queue. As 
Indicated at step 283, the CRM worker may repeat tiie 
steps 281-282 multiple times to enqueue multiple log 
records. 

[0067] After tiie CRM worker 202 has queued all tiie 
log records for the action tiiat the CRM worker 202 is 
about to take on tiie resource, tiie CRM worker 202 calls 
the "ForceLogO" metiiod on the ICrmLogControl Inter- 
face 230 of the CRM clerk 222 in step 284 to cause tiie 
queued log records to be written out to the persistent 
log 226. The separate "WriteLogRecordO" and "Force- 
LogO** methods thus allow the CRM worker 202 to 
queue up multiple log records and have them written 
together to the persistent log 226. which enhances log- 
ging efficiency. 

[0068] The implementation of the "WriteLog RecordQ," 
"WriteLogRecordVariantsOt" and "ForceLog methodsQ" 
in the CRM clerk 222 use the ILog interface 246 of the 
log object 240 to cache and then force written log 
records to the log file 244. 

Checkpoints 

[0069] Witii reference again to Figure 3, the persistent 
log 228 uses checkpoints to redaim space of log 
records from completed transactions in the log file 244. 
[0070] The CRM recovery clerk 224 periodically 
issues initiate check point requests to tiie recovery 
engine 242, by calling the "TakeCheckpointQ" method 
on the ILogRecGver interface 248. The CRM recovery 
clerk 224 has a background thread which waits on 
events or a timeout. On timeout, the CRM recovery clerk 
224 checks whether any log records have been written 
since the last checkpoint. If not. no checkpoint request 
is initiated. These periodic check point requests allow 
the recovery engine to automatically resize or grow the 
log file 244 if not suffident for tiie transaction rate and 
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volume of log records. 

[0071] The CRM recovery clerk 224 also checks 
whether there currently are any CRM clerks before initi- 
ating a check point request. If there are none, no check 
point request is initiated. If there cun^ently are CRM s 
clerks, the CRM recovery clerk 224 logs the clerk 
Instance identifiers of the CRM clerks so that the CRM 
clerks can be created correctly during recovery 
processing. The CRM recovery clerk 224 logs a single 
log record, the "clerk list record,** containing the clerk 
instance identifiers of all current CRM clerks. 
[0072] The CRM recovery clerk 224 further governs 
truncation of the log. During check point processing by 
the recovery engine 242, the recovery engine 242 
(using the "ILogRecoverClerk::WriteCheckpointO" 
method) has the CRM recovery cjerk 224 and each 
CRM clerk 222 write chec^DOint log records and return 
the minimum LSN used for their log records. The CRM 
recovery clerk 224 writes the derk list log record prior to 
issuing the initiate check point request to the recovery 
engine, then returns the LSN of the clerk list log record 
as its minimum LSN from the recovery engine's write 
check point request. This guarantees that the clerk list 
record occurs before any check point records of the 
CRM clerks 222 in the log file 244. and that the last two 
check points are nr\aintained in the log file 244. 
[0073] In response to the recovery engine's write 
check point requests to the CRM clerks, each CRM 
derk 222 copies Its log records fbnward on an every 
other check point basis. More specifically, the first time 
the CRM derk 222 is called with a write check point 
request and has a transaction In progress, the CRM 
derk 222 returns it minimum LSN in use. The next time, 
the CRM derk 222 copies forward alt its log records, 
and returns its new minimum LSN. In copying fonn/ard, 
the CRM clerk 222 reads all log records that it has writ- 
ten to the log file 244. and rewrites the log records to the 
log file 244. This approach means that only the last two 
checkpoints are retained in the log file 244, while reduc- 
ing the frequency at which, the CRM derk 222 must 
copy fonward Its log records. The persistent log 226 can 
then wrap to reuse space freed up from completed 
transactions. Preferably, the timeout interval of the CRM 
recovery clerk's initiate checkpoint requests is tuned so 
that most of the transactions complete within two check 
points and copy fonward normally is not required of the 
CRM clerk 222. 

[0074] The CRM clerk 222 begins writing a check 
point with a begin check point record and ends with an 
end check point record. This allows the boundaries of 
the check point to be accurately identified during recov- 
ery, and to determine whether the check point was com- 
pleted successfully or interrupted in a failure. The CRM 
clerk 222 further adds a sequence number to each log 
record that it writes, and adds a copy flag to log records 
that are copied fbnvard In a check point. When copying 
forget records (that identify a previous log record that is 
to be forgotten) fonvard, the CRM clerk 222 updates the 



forget record to properly identify the forgotten log record 
by its new (copied fonward) LSN. 
[0075] During check point processing, the CRM clerk 
222 blocks new log record writes from the CRM worker 
202 or CRM compensator 206 so as to preserve the 
order of log records written via the CRM clerk. Also, two 
phase commit notifications are blocked while a check 
point is in progress. Check point requests likewise are 
blocked during normal writes to the persistent log 226 
and during processing transaction completion notifica- 
tions. 

Compensating 

[0076] In the illustrated CRM architecture 200 of Fig- 
ure 3. tiie transaction manager 148 (Figure 2) provides 
tiie two phase commit notifications to ttie compensating 
resource manager through the ITransactionResour- 
ceAsync interface 238 of the recovery engine 242 
(which enlisted on the transaction during registration of 
the CRM derk 222 witii the recovery engine). For each 
notification, the recovery engine 242 reads all log 
records that have been written to tiie log in assodation 
witii the clerk instance identifier of the CRM derk 222 
(which indudes the log records written by the CRM 
worker 202 for its normal action). The recovery engine 
242 then passes the notification and log records to tiie 
CRM clerk 222 using the ILogReooverClerkPhaseNotif i- 
cation Intertece (described below) of the CRM derk. 
[0077] The CRM clerk 222 responds to the recovery 
engine's calls by creating the CRM compensator 206 
using tiie CLSID registered with tiie CRM resource dis- 
penser 220. The CRM clerk 222 then calls a metiiod of 
tiie ICrmCompensator (in tiie unstructured log records 
case) or ICrmCompensatorVariants (structured log 
records case) interface 212 on the CRM compensator 
206 tiiat is appropriate to tiie respective two phase com- 
mit notification (e.g., the BeginPrepareQ. PrepareRe- 
cordO. and EndPrepareQ for the prepare phase 
notification). The CRM clerk 222 additionally passes a 
pointer to its ICrmLogConta^ol internee In a call to tiie 
"SetLogContror method on the ICrmCompensator (or 
ICrmCompensatorVariants) interface 212 of the CRM 
compensator 206, which the CRM compensator uses 
for logging its compensating action. 
[0078] The implementation of the two phase commit 
notification methods in the CRM compensator 206 per- 
forms the appropriate actions specific to tiie resource 
for the action logged by the CRM worker. (As noted 
above, the implementation of the CRM compensator is 
provided by the developer, e.g., a systems integrator or 
otiier programmer, of the compensating resource man- 
ager for a particular resource.) In the prepare notifica- 
tion methods (i.e., " Begin PrepareQ," "Prepare RecordQ** 
and "EndPrepareQ"). the CRM compensator 206 deter- 
mines whetiier the work done on the resource in tiie 
transaction is properly prepared to commit. In tiie case 
of most implementations of the CRM compensator, the 
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work of the CRM worker 202 in the transaction has 
already been niade persistent on the resource at the 
time it was performed by the CRM worker. The CRM 
compensator therefore can be implemented so as to 
simply set the "bOkToPrepare" parameter of the "End- 
PrepareO" method to "VARIANT.TRUE" and return. In 
other implementations, the CRM compensator 206 may 
perform checks to determine whether the work should 
remain persisted or be compensated, and set the "bOk- 
ToPrepare" parameter accordingly For example, the 
check may determine whether the work done by the 
CRM worker is conrect or consistent. 
[0079] For the commit notifications (e.g., the "Begin- 
CommitO," "CommitRecordO" and "EndCommitQ" 
methods), the CRM compensator 206 can perform any 
clean-up actions to complete the work of the CRM 
worker on the resource. For example, where the 
resource is a file system and the compensating 
resource manager is to provide the capability to delete 
files within a transaction, the CRM worker's normal 
action may be to rename or hide the file to be deleted, 
so that the file can be restored on an abort of the trans- 
action. The CRM compensator In this example perfbrms 
a clean-up action that actually deletes the renamed or 
hidden file upon a commit of the transaction. The CRM 
compensator receives the log records of the CRM 
worker's action (via the "CommitRecordQ" method), 
such as to read the name of the renamed or hidden file. 
The CRM compensator also uses the ICrmLogControl 
interface of the CRM clerk 222 to log the dean-up 
actions for recovery purposes. The CRM compensator 
writes the log information after performing the clean-up 
action to ensure tiie clean-up action is taken. In the 
above example of the delete file compensating resource 
manager for instance, the CRM compensator 206 logs 
that the renamed or hidden file has been deleted after 
deleting the file. If a failure then occurs during the com- 
mit phase of the transaction, the clean-up action can be 
omitted during subsequent recovery. The clean-up 
action Implemented in the "EndCommitQ" method 
should be idempotent, so that it may be attempted mul- 
tiple times with the same results as if it succeeds on the 
first attempt. Such as in a case where a failure occurs 
after the CRM compensator perfbrms tiie clean-up 
action but before logging that tiie clean-up action was 
done, or when failures occur during recovery 
[0080] In the abort notification methods, the CRM 
compensator 206 performs an idempotent compensat- 
ing action to reverse the work of tiie CRM worker 202 
that typically is already persisted on the resource. The 
CRM compensator receives tine information logged by 
the CRM worker witii tiie "Abort RecordQ" metiiod. The 
CRM compensator also logs the compensating action 
witii the CRM clerk 222 on a write-after basis. In the 
above example of the delete file compensating resource 
manager for Instance, the CRM compensator can be 
Implemented so as to restore the renamed or hidden file 
In ttie "EndAbortO" metiiod. 



[0081 ] After the CRM compensator successfully com- 
pletes processing its compensating actions for the com- 
mit or abort notification, the CRM clerk 222 writes a 
clerk end log record to the persistent log 226 to Indicate 
5 it processing its done and the CRM clerk 222 can be 
released. The CRM clerk 222 also notifies tiie CRM 
recovery clerk 224 so tiiat it can be removed from tiie 
list of currently registered CRM clerks. 

10 Recovery 

[0082] In the Illustrated CRM architecture 200 shown 
in Figure 3, the system-provided infrasti-ucture (e.g.. the 
CRM recovery clerk 224 and tiie recovery engine 242) 

15 also perform recovery after a failure occurs that inter- 
rupts normal processing. Recovery is initiated on star- 
tup of the ASP 90 (Fig 2). During startup processing of 
the ASP 90, the CRM architecture 200 is loaded into the 
ASP, and the CRM recovery clerk 224 is created. At 

20 Start-up, the CRM recovery derk 224 looks for the log 
file 244 associated with tiie ASP As described above, 
tiie log file 244 has a file name based on an Identifier 
(the Appki) of the ASP. and resides on a same file sys- 
tem path as a log file of the transaction manager 148 

25 (Figure 2). If tiie log file 244 exists for the ASP. the CRM 
recovery clerk initiates recovery on tiie log file 244 (e.g., 
by creating the recovery engine 242 and calling the "ILo- 
gRecover::RecoverO" metiiod of tiie recovery engine). 
[0083] The recovery engine 242 implements recovery 

30 processing according to the ARIES recovery protocol, 
and drives each clerk tiiat was registered with tiie 
recovery engine (e.g., the CRM recovery clerk 224 and 
each CRM clerk 222) through analysis, redo and undo 
phases of recovery processing (using the ILogRecover- 

35 Clerk interface implemented on the CRM recovery clerk 
224 and each CRM clerk 222). During normal process- 
ing, the CRM recovery clerk 224 logs clerk list log 
records (prior to check points) and new clerk log records 
(when a new CRM clerk is created between check 

40 points). Due to the way the CRM recovery clerk logs 
these records, tiie clerk list and new clerk records iden- 
tifying the CRM clerk 222 precede (i.e.. have lower 
LSNs) any records logged by such CRM clerk in tiie log 
file 244. During recovery, the recovery engine therefore 

45 causes the CRM recovery clerk 224 to perform recovery 
processing of tiie records identifying the CRM derk 222 
prior to causing the CRM clerk 222 to perform recovery 
processing of the log records tiiat the CRM clerk wrote. 
When processing the clerk list and new clerk log 

so records in tiie analysis phase of recovery, tiie CRM 
recovery clerk 224 creates a new CRM clerk for each 
derk instance identifier identified in tiie records, and 
assigns it the respective clerk instance identifier. The 
created CRM derk identifies itself to the recovery 

55 engine 242 witti tiie assigned derk instance identifier 
and Is then available to receive tiie log records logged 
with that clerk Instance kjentifier from tiie recovery 
engine. The CRM clerk 222 is responsible for properly 
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interpreting the log records, creating the registered 
CRM compensator 206 and cailing the appropriate 
methods on the CRM compensator according to the 
transaction outcome. 

[0084] In the analysis phase, the recovery engine 242 
passes all log records associated with the clerk 
instance identifier of the CRM clerk 222 to the CRM 
clerk (via the "ILogRecoverClerk:: Analyze RecordQ" 
method). The CRM clerk analyzes the log records to 
perform the appropriate recovery processing. First, the 
CRM clerk looks for a dark end record. The CRM clerk 
logs a derk end record during normal processing only 
after the compensating action of the CRM compensator 
on a commit or abort notification. If a clerk end record is 
detected, the CRM derk 222 condudes that the trans- 
action completed successfully (including the compen- 
sating actions of the CRM compensator 206) and no 
recovery is necessary for this instance of tiie CRM 
clerk. 

[0085] If no derk end record is detected, the CRM 
clerk 222 proceeds to identify a correct sequence of the 
log records originally written by the CRM clerk. The 
CRM clerk 222 may have survived through multiple 
check points t>efbre the failure, resulting in duplicate 
copies of some log records with okl LSNs. The CRM 
clerk 222 orders the log records It receives from the 
recovery engine 242 by their LSN. The CRM clerk 222 
processes the log records to ensure that only one 
record with a given sequence number exists. Any dupli- 
cates are discarded. Additionally, the CRM clerk 222 
processes the list for forget log records, and marks the 
log records that are to be forgotten. The resulting list is 
the correct log record sequence for the CRM clerk 222. 
[0066] During its analysis phase, the CRM clerk 222 
also looks for a clerk begin record in which the CRM 
clerk logged the class identifier of the CRM compensa- 
tor which was registered by the CRM worker 202. At the 
end of its analysis phase, the CRM clerk 222 returns the 
least LSN in the identified log record sequence to the 
recovery engine 242. 

[0087] After the analysis phase, the recovery engine 
242 further drives the CRM recovery clerk 224 and each 
CRM clerk 222 through redo and undo phases (via 
"BeginRedoPassO," "Redo RecordQ." "BeginUndo- 
PassQ" and "UndoRecordQ" methods of the ILogRecov- 
erClerk interface), and also delivers notifications to the 
CRM clerk as to the status of the CRM clerk's transac- 
tion (via the IRecoverClerkPhaseNotification interface). 
The CRM recovery clerk 224 and the CRM clerk 222 
ignore the redo and undo phases of recovery. The 
recovery engine 242 determines the transaction status 
from log records that it logged during normal process- 
ing, or by again enlisting on the transaction with the 
transaction manager 148 (Figure 2). 
[0088] If the recovery engine 242 finds a prepare 
record logged for the transaction, the recovery engine 
delivers a prepare notification to the CRM clerk 222 
having the transaction during recovery (via the "OnPre- 



pareQ" method of the IRecoverClerkPhaseNotification 
interface). However, since prepare is not meaningful to 
the CRM compensator during recovery, the CRM clerk 
222 does not pass the prepare notification to the CRM 

5 compensator. 

[0089] Upon determining that the transaction was 
committed or aborted, the recovery engine 242 delivers 
the appropriate notification to the CRM clerk 222 having 
the transaction during recovery (via the "OnCommitQ" 

10 or "OnAbortO" methods of the IRecoverClerkPhaseNo- 
tification interface). As during normal processing, the 
CRM clerk 222 responds to these notifications by creat- 
ing the CRM compensator, and delivering the commit or 
abort notification to the CRM compensator along with 

15 the log records that were written by the CRM worker (via 
the "BeginCommitQ," "CommitRecordO." "EndCom- 
mitO." "BeginAbortO." "AbortRecordO" and "End- 
AbortO" methods of the ICrmCompensator interface 
212). This causes the CRM compensator to perform the 

20 appropriate clean-up action (for commit) or compensat- 
ing action (for abort) based on the log records. After the 
CRM oonpensator successfully completes this 
processing, the CRM clerk 222 writes a derk end record 
to indicate Its processing is done, and the CRM clerk 

25 can be released. The CRM derk 222 also notifies the 
CRM recovery clerk 224 so that is can be removed from 
the list of registered CRM clerks. 
[0090] If the recovery engine 242 determines that the 
transaction is in doubt upon re-enlisting on the transac- 

30 tion with the transaction manager 148 (Figure 2). the 
recovery engine so notifies the CRM clerk 222 having 
the transaction (via the "OnlnDoubtQ" method of the 
ILogRecoverClerk interface). In this case, the CRM 
derk is responsible for maintaining its log records in the 

35 log file 244 through ail subsequent check points. 

[0091 ] At the end of recovery, the recovery engine 242 
notifies the CRM recovery clerk 222 and the CRM clerk 
224 that recovery is completed (via the "EndRecov- 
eryO" method of the ILogRecoverClerk interfece). If its 

40 transaction was completed during recovery, the CRM 
derk 222 is released. The CRM recovery derk 224 
remains after recovery to maintain the list of registered 
CRM clerks and to initiate check point requests. 

45 Human Compensation 

[0092] In some compensating resource managers 
implemented with the CRM architecture 200 (Figure 3). 
the CRM compensator 206 can use human compensa- 

50 tion as part of its clean-up and/or compensating actions. 
As part of the two phase commit protocol, it Is essential 
that the compensating resource manager be able to 
perform the appropriate actions to commit or abort the 
transaction after voting affirmatively in the prepare 

55 phase. In compensating resource managers using 
human compensation, the CRM compensata relies on 
human action In cases where the clean-up or compen- 
sating action fails. On such failure, the CRM oompensa- 
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tor provides output to inform a human operator to take 
appropriate manual action to correct the situation. The 
CRM compensator then continues as if the clean-up or 
compensating action had succeeded, such as logging 
appropriate information and indicating "success" (i.e.. 
as the HRESULT return value of the method) on return 
from the "EndCommitQ** or "EndAbortQ" call. If neces- 
sary, the CRM compensator can request that the CRM 
clerk 222 replay the log records from the start by return- 
ing an error code to the CommitRecordQ" or "Abor- 
tRecord" calls by which the log records are delivered 
from the CRM clerk. This allows the full sequence of log 
records to be saved to a separate file for use in later 
human compensation when the failure that requires 
human compensation occurs part way through the CRM 
compensator's processing of the log records. 
[0093] The notice to the human operator can be In the 
form of an on-screen visual notice, audio notice, print- 
out report, or other notice. Usually, so as to provide suf- 
ficient information for the human operator to perform the 
required manual corrective action, the notice will include 
the log records relevant to the transaction in human 
readable format, or othenwise provide a way for the 
human operator to inspect such records (e.g.. writing 
the log records to a separate file viewable by the human 
operator using a log viewing utility). 
[0094] For example, a compensating resource man- 
ager that effects credit card billing may use human com- 
pensation as part of the compensating action for a 
credit card charge. The compensating action where the 
transaction aborted is to perform a credit to the account. 
If the CRM compensator is unable to credit the account, 
such as due to unavailability of another computer or 
communications link needed to access the account 
information, the CRM compensator can instead perform 
the compensating action through human intervention. 
The CRM compensator notifies the human operator that 
manual action is needed, and may provide access to tiie 
log records for the operator to determine which account 
to credit and the amount. 

Deferred Recovery 

[0095] In some compensating resource managers 
implemented with the CRM architecture 200 (Figure 3), 
the CRM compensator 206 alternatively can use 
deferred recovery as part of its clean-up and/or com- 
pensating actions. With deferred recovery, the log 
records of the CRM worker's normal actions remain in 
the persistent log 226 when tiie clean-up or compensat- 
ing action of the CRM compensator 206 fails during nor- 
mal processing or during recovery processing. The 
CRM compensator 206 returns a failure result from the 
"EndCommitO" or "EndAbortQ" metiiods. Since the 
commit or abort phase of the transaction does not com- 
plete, the transaction continues to exist and the transac- 
tion manager 148 (Rgure 2) retains information on the 
transaction. The CRM architecture 200 and MTS execu- 



tion environment 82, however, continue with recovery 
processing (if during recovery) and also normal 
processing of otiier transactions. In a later recovery, tiie 
CRM clerk 222 causes tiie CRM compensator 206 to 
5 re-attempt the defenred clean-up or compensating 
action. 

Interface Definitions 

10 [0096] The ICrmlnOgCQntrQl Interface, with reference 
again to Figure 3. the CRM clerk 222 supports tiie ICrm- 
LogConfrol interface 230. The ICrmLogControl interface 
230 is used by tiie CRM worker 202 and possibly also 
the CRM compensator 212 to write records to the per- 

15 sistent log 226. The CRM worker 202 also registers its 
counterpart CRM compensator 212 witii the CRM clerk 
222 using the ICrmLogControl interface 230. 
[0097] The ICrmLogControl interface provides a set of 
metiiods as shown in tiie program listing of Figure 6. 

20 The TransactionUOWQ" metiiod is used by the CRM to 
obtain a Transaction Unit Of Work identifier of tiie trans- 
action In which the CRM worker performs its normal 
action. 

[0098] As discussed above, the CRM worker 202 calls 

25 the "RegisterCompensatorQ'* metiiod to register its 
counterpart CRM compensator 206 with tiie CRM clerk 
222. The CRM worker 202 calls the metiiod first after 
obtaining a pointer to the ICrmLogControl interface (i.e.. 
before using the interface to write any log records to tiie 

30 persistent log), and can only call the method success- 
fully once (subsequent attempts or an attempt by the 
CRM compensator to call the method result in an 
E.FAIL return value). The CRM worker 202 specifies a 
class identifier (CLSID) or program identifier (PRCXSID) 

35 in string format of the CRM compensator 206 as the 
"IpcwstrProgldCompensator" parameter in the call. The 
CRM worker 202 also passes a text desaiption in tiie 
"IpcwstrDescription" parameter to be used for nfK>nitor- 
Ing or administration. In addition to CRM compensator 

40 registration, the method also performs a number of vali- 
dation checks to ensure that tiie CRM can proceed. 
These checks include verifying that tiie CRM compen- 
sator can be created, and supports at least one of the 
ICrmCompensator or ICrmCompensatorVariants inter- 

45 faces (described below). If not, tiie metiiod returns 
"E^FAIL" or "E_NOINTERFACE" values, respectively. 
The method furtiier checks that the cun-ent context has 
valid transaction and activity identifiers. Finally, if the 
CRM recovery clerk has not completed recovery 

50 processing, or if it has detected fafal errors for the CRM. 
tiien the metiiod returns values. 
"XACT_E_RECOVERYINPROGRESS" or "E_FAIU" 
respectively. 

[0099] The "WriteLog Record VariantsQ" method is 
55 called by the CRM worker 202 and CRM compensator 
206 to write structured log records to the log. Structured 
records are records made up as a collection of Variant- 
type values. Typically, ttiis method Is used where the 
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CRM worker arxJ CRM compensator are written in 
Microsoft Visual Basic, and the structured record is a 
Visual Basic Collection object. The method returns a 
failure code. "E^FAIU" if the CRM compensator 206 
that was registered by the CRM worker 202 does not 5 
support the ICrmCompensatorVariants interfoce. The 
CRM worker and CRM compensator are not permitted 
to use both structured and unstructured log records. 
Accordingly, a call to this method after a previous suc- 
cessful call to the "WrrteLogRecordQ" method will return 10 
an "E.FAIL" value. The method also will return, the 
"E^FAIL" value H called by the CRM worker 202 after 
the transaction has completed or is in the process of 
completing. However, the CRM compensator can con- 
tinue to use the method to write further log records dur- 15 
ing transaction outcome notifications. 
[0100] The "ForceLogO" method is called by the CRM 
worker 202 and CRM compensator 206 to cause log 
records that were previously written using the "WriteLo- 
gRecordO" or "WriteLogRecordVariantsQ" methods to 20 
be written out to the persistent log 226, which is In per- 
sistent memory of the computer (e.g., the hard drive 27 
in Figure 1) where it survives failure. With the log infor- 
mation persisted, the CRM worker 202 can proceed 
with its normal action on the resource. 25 
[0101] The "ForgetLogRecordO" method is called by 
the CRM worker 202 or CRM compensator 206 to 
cause the CRM derk to forget the last log record that 
was written (e.g.. using the "WriteLogRecordQ" or 
"WriteLogRecordVariantsO" methods). In the illustrated 30 
CRM architecture 200, the method can only be used to 
forget the last log record written, and does not allow 
nesting. The forgotten log record is not delivered to the 
CRM compensator during two phase commit notifica- 
tions. 35 
[0102] The CRM worker 202 calls the "ForceTransac- 
tionToAbortO'* method to unilaterally cause the transac- 
tion to immediately abort (e.g., via a call to the MTS 
ITransaction::Abort method. . as described in more 
detail in the above incorporated MTS Patent Applica- 40 
tions). A call to the method from the registered CRM 
compensator 202 returns a failure code "E^FAIL." 
because the CRM compensator Is not active unless the 
transaction is in the process of completion. 
[0103] The "WriteLogRecordO" method is called by 4S 
the CRM worker 202 or CRM compensator 206 to write 
unstructured log records (which typically are used 
where the CRM worker and CRM compensator are writ- 
ten in Miaosoft Visual C++ or Visual J-m-). The unstruc- 
tured records are simply a buffer of bytes. The method so 
provides a gathering capability by allowing sections of 
the log record to built up by the CRM worker (or com- 
pensator) as an array of such buffers (the "rgBlob" 
parameter), which are then copied to a buffer main- 
tained by the CRM derk in a single operation by this ss 
method. The method will return a failure code 
("E.FAIL*^ in the following cases: (1) the registered 
CRM compensator does not support the ICrmCompen- 
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sator interface, (2) the method was called after a previ- 
ous successful call to the "WriteLogRecordVariantsQ" 
method (since the CRM clerk does not allow structured 
and unstructured records to be mixed), and (3) the CRM 
worker calls the method after the transaction has com- 
pleted or is in the process of completing. 
[0104] The ICrmCompensator and ICrmCompensa- 
torVariants interfaces. With reference still to Figure 3, 
the CRM compensator 206 supports one or both of the 
ICrmCompensator or ICrmConpensatorVariants inter- 
faces 212. The interlaces are used by the CRM clerk 
222 to deliver two phase commit notifications, and the 
records logged by the CRM worker 202 during its nor- 
mal action to the CRM compensator. As discussed 
above for the I CrmLog Control interface, the records for 
a particular CRM are required to be all either structured 
or unstructured depending on whether the "WriteLo- 
gRecordVariantsO" or "WriteLogRecordQ" method was 
used, respectively The ICrmCompensator interface is 
used to deliver unstructured log records, while the ICrm- 
CompensatorVariants interface delivers structured log 
records to the CRM conpensator. 
[0105] The ICrmConpensator and ICrmCompensa- 
torVariants interfaces are defined in the program listings 
302-303 shown in Figures 7 and 8. The "SetLogCon- 
trolO" method is called by the CRM derk 222 first after 
creating the CRM compensator 212 to pass a pointer to 
the CRM derk^s ICrmLogControl interface 230 (as the 
"pLogContror parameter) to the CRM compensator 
212. This allows the CRM Compensator to write further 
log records during transaction completion. A return 
value other than ''S_OK" from this method is considered 
an error of the CRM compensator that will cause a ''fail- 
fast" of the ASP 90. unless specifically overridden via a 
registry flag for the CRM compensator CLSID. 
[0106] The "BeginPrepareO" method is called by the 
CRM clerk 222 as the prepare notification (phase 1 of 
the two phase commit protocol) to the CRM compensa- 
tor, and indicates that log records are about to be deliv- 
ered. The prepare notification is sent only during normal 
processing, arvl not during recovery Again, a return 
value other than "S.OK" is considered a CRM compen- 
sator error. 

[01 07] The "PrepareRecordO" method is called by the 
CRM derk 222 to deliver a log record to the CRM com- 
pensator 206 during the prepare phase. The log records 
are delivered in fonn/ard order. Unstructured log records 
are delivered as a XrmLogRecordRead** data struc- 
ture, which contains a flags field (''dwCrmFlags'*). a 
sequence number ("dwSequenceNumber"). and the log 
record data ('t)lobUserData"). The flags fieki and 
sequence number provide information that may be use- 
ful for debugging or fault identification in circumstances 
where human compensation is necessary. The flags 
field indudes flags that indicate whether the record was 
forgotten, and when the record was written. The 
sequence number of the log record indicates its 
sequence in the persistent log 226. The CRM compen- 
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sator 206 can set the forget flag (the "pfForget" param- 
eter) on return from the method to cause the CRM clerk 
to forget the log record delivered by the method call. 
The CRM compensator can return the value 
"ERROR_REPLAY_RECORDS" to cause the CRM 
clerk 222 to repeat delivery of all the log records written 
by the CRM worker, Including also those that were for- 
gotten and those written by the CRM compensator dur- 
ing the prepare phase. A return value other than 
"S_OIC or "ERROR.REPLAY.RECORDS" is consid- 
ered a CRM compensator error that causes a failfast of 
the ASP 90. The "PrepareRecordVariantsQ" method is 
similar to the "PrepareRecordQ" method, but delivers 
structured log records. 

[0108] The "EndPrepareO" method is called by the 
CRM derk 222 to indicate that all log records available 
during the prepare phase have been delivered. If no log 
records were written by the CRM worker 202, the CRM 
clerk omits calling the PrepareRecord or "PrepareRe- 
cordVariantsO" methods between its calls to the "Begin- 
PrepareO" and "EndPrepareQ" methods. The CRM 
compensator votes on the transaction outcome using 
the "fOkToPrepare" parameter A return value other 
than "S_OK" is considered a CRM compensator error 
that causes a failfast of the ASP 90. 
[01 09] The CRM clerk 222 calls the "BeginCommitO" 
or "BeginAbortO" methods to deliver a commit or abort 
notification, respectively, to the CRM compensator The 
call also indicates to the CRM compensator that log 
records are about to be delivered for processing the 
commit or abort actions by the CRM compensator 206. 
The *'f Recovery" parameter is a flag indicating whether 
the method is being called during recovery or normal 
processing. A return value other than "S.OK" is consid- 
ered a CRM compensator error that causes a failtet of 
the ASP 90. 

[0110] The "CommitRecordO" and "AbortRecordQ" 
methods are called by the CRM clerk 222 to deliver an 
unstructured log record during the commit or abort 
phase processing. For structured log records, the CRM 
clerk calls the similar "CommitRecordVariantsQ" or 
"AbortRecordVariantsO" methods. For the "Com- 
mitRecordO" method, the CRM clerk 222 delivers log 
records in the fonvard order. For the "AbortRecordQ" 
method, the CRM clerk 222 delivers log records In 
reverse order, tf no log records were written, the CRM 
clerk 222 omits calling the XommitRecordQ" (or "Abor- 
tRecordQ") between "BeginCommitQ" (or "Begi- 
nAbortO") and "EndCommitQ" (or "EndAbortQ") calls. 
The CRM compensator can set the forget flag parame- 
ter ("f Forget") on return to cause the CRM clerk 222 to 
forget the delivered log record. A return value other than 
"S^OIC or "ERROR.REPLAY_RECORDS" is consid- 
ered a CRM compensator enx3r that causes a failfast of 
the ASP 90. 

[0111] The "EndCommitO" and "EndAbortO" methods 
are called by the CRM clerk 222 to notify the CRM com- 
pensator that ail log records have been delivered during 



the commit or abort phase. The CRM clerk 222 is free to 
discard all log records for the transaction upon success- 
ful completion of this method. A return value other than 
''S_OK" is considered a CRM compensator error that 

5 causes a failfast of the ASP 90. 

[01121 The ILooRecover Interface. The recovery 
engine 242 supports the ILogRecover interface 248. 
The interface is used by the CRM recovery clerk 224 to 
initiate checkpoints during normal processing (via a call 

10 to the "TakeCheckpointO" method), and to initiate recov- 
ery on the log file 244 during recovery processing (via 
the "RecoverO" method). The ILogRecover interlace is 
defined in the program listing 306 shown in Figure 10. 
[0113] The ILogRecoverClerk interface. The CRM 

15 recovery clerk 224 and each CRM clerk 222 implement 
the ILogRecoverClerk interface. The recovery engine 
242 uses the ILogRecoverClerk interface to drive the 
CRM recovery clerk 224 and the CRM cleri< 222 
through phases of recovery, and deliver the log records 

20 related to such clerk during the recovery phases. The 
recovery engine 242 also uses the ILogRecoverClerk 
interface to cause the CRM recovery derk 224 and the 
CRM clerk 222 to perform their check point processing 
(via the "WriteCheckpointQ" method). The ILogRecover- 

25 Clerk interface is defined by the program listing 308 
shown in Rgure 1 1 . 

[01 1 4] The ILooRecoverClerkPhaseNotification Inter- 
tQQS^ The CRM clerk 222 implements the ILogRecover- 
ClerkPhaseNotification interface. As the recovery 

30 engine 242 receives two phase commit notifications 
from the transactions in which it has enlisted, the recov- 
ery engine uses the ILogRecoverClerkPhaseNotifica- 
tion interface to pass the notification to the CRM clerk 
222 that has the transaction. The ILogRecoverClerk- 

35 PhaseNotification interface is defined in the program- 
ming listing 310 shown in Rgure 12. 
[01 1 5] The ILoqRecoverClerkReaistration Interface. 
The recovery engine 242 supports the ILogRecover- 
ClerkRegistration. which is called by the CRM recovery 

40 derk 224 and the CRM derk 222 to register with the 
persistent log 226. As described above, the CRM recov- 
ery clerk 224 registers its class identifier (CLSID) with 
the recovery derK while the CRM clerk registers a clerk 
insfance Identifier that uniquely identifies the CRM clerk 

45 222 among other CRM clerks of the same class. The 
ILogReooverCleritRegistration interface is defined in the 
program listing 312 shown in Figure 13. 
[01 1 6] The ILoa Interface. The log object 240 imple- 
ments the ILog interface, which provides services to the 

so CRM derk 222, the CRM recovery clerk 224 and the 
recovery engine 242 for stably writing log records to the 
log file 244. The ILog interface is defined in the program 
listing 314 shown in Figure 14. 
[01 1 7] Having described and illustrated the principles 

55 ,of my Invention with reference to an illustrated embodi- 
ment. It will be recognized that the Illustrated embodi- 
ment can be modified in arrangement and detail without 
departing from such prindples. It should be understood 
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that the programs, processes, or methods described 
herein are not related or limited to any particular type of 
computer apparatus, unless indicated othenMse. Vari- 
ous types of general purpose or specialized computer 
apparatus may be used with or perform operations in 
accordance with the teachings described herein. Ele- 
ments of the illustrated embodiment shown in software 
may be implemented in hardware and vice versa. 
10118] For example, while the illustrated CRM archi- 
tecture 200 provides an interface (the ICrmLogCon- 
trohiRegisterCompensatorO" method) to register the 
CRM compensator 206. compensating resource man- 
agers according to the invention can alternatively log an 
identification (e.g., CLSID or PROGID) of the compen- 
sator object in the log information written to the persist- 
ent log 226 to be used by the system-provided 
Infrastructure (e.g.. the CRM clerk 222 and the CRM 
recovery clerk 224} to create the compensator compo- 
nent to process two phase commit notifications of the 
transaction manager 146 (Rg 2). 
[01 1 9] In view of the many possible embodiments to 
which the principles of my invention may be applied, it 
should be recognized that the detailed embodiments 
are illustrative only and should not be taken as limiting 
the scope of my invention. Rather, I claim as my inven- 
tion all such embodiments as may come within the 
scope and spirit of tiie fbllowing claims and equivalents 
thereto. 

Claims 

1. In an on-line transaction processing system, a 
method of managing a resource within a transac- 
tion, the resource durably storing data of a server 
application, the mettiod comprising the steps of: 

on request of the server application, performing 
work on tiie data as part of a transaction: 
persisting ttie results of the work on tiie data in 
the resource at tiie time of tiie request; 
issuing a notification indicative of a phase tran- 
sition of the transaction; and 
in response to the notification indicating the 
transaction is aborted, performing a compen- 
sating action to reverse tiie persisted work on 
the data in the resource. 

2. In a computer, a component-based framework for 
managing a durable resource to participate witiiin a 
transaction under control of a transaction manager, 
the transaction manager transmitting notifications 
to participating components according to a two- 
phase commit protocol, the framework comprising: 

a log storage for durably recording log entries; 
a compensating resource manager operating 
in response to a client application request to 
perform work persistentiy altering data heki In 



the durable resource within tiie scope of a 
transaction, the compensating resource man- 
ager logging information in the log storage suf- 
ficient to fully reverse tiie work; and 
5 the compensating resource manager operating 

in response to a notification from tiie transac- 
tion manager indicating the transaction aborted 
to perform a compensating action according to 
the logged information to fully reverse the work. 

10 

3. TTie component-based framework of claim 2 
wherein tiie compensating resource manager com- 
prises a worker component and a compensator 
component, the worker component operating to 

15 perform tiie work and log tiie information in tiie log 
storage, tiie compensator component operating to 
perform tiie compensating action according to tiie 
logged information, the worker component passing 
information to the compensator component solely 

20 by way of tiie log storage. 

4. A computer-readable storage medium having 
stored thereon computer-executable program code 
of a component-based resource management 

25 framework for integrating a durable resource into a 
ti-ansaction processing system so as to participate 
within a transaction under control of a transaction 
manager, said integrating being tiirough use of a 
worker component operative to perform a work 

30 operation on the durable resource at request of an 
application and a compensator component opera- 
tive to perform a compensating operation tiiat 
reverses tiie work operation, the component-based 
framework comprising: 

35 

a compensator registering component having a 
compensator registration interface for calling 
by the worker component to register the com- 
pensator component; 
40 a logging component having a logging interface 

fbr calling by the worker component to persist- 
ently log information of the work operation; 
a compensation initiating component having a 
notification interface fbr receiving notification 
45 from the transaction manager that tiie transac- 

tion is to abort, and operative to create ttie 
compensator component and further operative 
in response to the notification to cause the 
compensator component to perform the corn- 
so pensating operation based on the information 
logged by tiie work component to ttiereby 
reverse ttie work operation. 

5. The computer-readak)le storage medium of claim 4 
55 wherein tiie compensator registering component 

passes a pointer to tiie logging interface to tiie 
worker component on return from tiie wori<er com- 
ponenfs call to the compensator registration Inter- 
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face. 

6. The computer-readable storage medium of claim 4 
wherein the compensator registering component is 
further operative in response to the worker compo- 
nent's call to the compensator registration interface 
to enlist the compensation initiating component in a 
transaction in which the worker component partici- 
pates, such that the compensation initiating compo- 
nent receives the notification from the transaction 
manager. 

7. The computer-readable storage medium of claim 4 
wherein the compensation initiating component is 
further operative to receive a prepare notification 
from the transaction manager on the notification 
interface, and operative in response to the prepare 
notification to cause the compensator component 
to perform a vote operation as to whether to abort 
the transaction in a prepare phase of the transac- 
tion. 

8. The computer-readable storage medium of claim 4 
wherein the compensation initiating component is 
further operative to receive a commit notification 
from the transaction manager on the notification 
interface, and operative in response to the commit 
notification to cause the compensator component 
to perform a clean-up operation and any real oper- 
ation according to the logged information to com- 
plete work partly accomplished by the work 
operation. 

9. In an on-line transaction processing system having 
a transaction manager, a compensating resource 
manager for managing a durable resource to partic- 
ipate within a transaction under control of the trans- 
action manager, the compensating resource 
manager comprising: 

a worker component having a work request 
interface for calling by an application to request 
a work operation on the durable resource as 
part of the transaction, the worker component 
operating in response to the application call to 
persistently write information pertaining to tiie 
requested work operation into a log and to per- 
form a work action to effect the work operation 
on the durable resource; and 
a compensator component having a notifica- 
tion interface for receiving a notification issued 
by the transaction manager to abort the trans- 
action, the compensator component operating 
in response to the notification to read the infor- 
mation from the log and to perform a compen- 
sating action to reverse the effect of the work 
action on the durable resource; 
wherein the worker component and the com- 



pensator component share state solely tiirough 
the information logged by the worker compo- 
nent. 

5 10. The compensating resource manager of claim 9 
further comprising: 

a compensation manager having a compensa- 
tor registration interface for calling by the 
10 worker component to register the compensator 

component, the compensation manager oper- 
ating in response to the worker component call 
to create the compensator component and 
enlist in the transaction to receive the notifica- 
15 tion issued by the transaction manager. 

11. The compensating resource manager of claim 10 
wherein the compensation manager is further oper- 
ative in response to ttie worker component call to 

20 provide access for the worker component to write 
tiie information to the log. 

1 2. The compensating resource manager of daim 9 for 
further recovering after failure during the transac- 

25 tion. the oonpensating resource manager compris- 
ing: 

a recovery manager operative when recovery 
is initiated after the failure to determine an out- 
30 come of the transaction from the transaction 

manager, to create the compensating compo- 
nent, and to cause tiie connpensating compo- 
nent to perform the compensating action based 
on the information from ttie log if the outcome 
35 was to abort the transaction. 

13. The compensating resource manager of claim 12 
wherein the recovery manager is further operative 
on failure of the compensating component to per- 

40 form ttie compensating action during recovery, to 
preserver ttie information in the log so as to defer 
the compensating action to a subsequent recovery. 

14. The compensating resource manager of claim 9 
45 wherein the compensating component is operative 

on failure to perform ttie compensating action dur- 
ing recovery, to cause notice and information to be 
provided to a hunnan operator for the human opera- 
tor to take manual action that reverses the normal 
so action on the durable resource. 

15. The compensating resource manager of claim 9 
wherein the compensating action of the compen- 
sating component is idempotent 

55 

16. The compensating resource manager of claim 9 
wherein the compensating action of the compen- 
sating component is not reversible. 
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/ 

300 [ object. 
\ uuid(F0BAF8E3-7804-1 1 d 1 -82E9-00A0C91 EEDE9). 

helpstring("ICrmLogControl Interface"), 
pointer_default{unique)] 

interface ICrmLogControl : I Unknown 
{ 

// get the Unit Of Work (UOW) identifier for the current transaction 
// will be returned as a stringized GUID of form 
//{7BB101F1-92B6-.11d1-82EC-00A0C91EEDE9} 
[propget, ld(1), helpstring("property TransactionUOW")J 
HRESULTTransactlonUOW([out, retval] BSTR * pVal); 

// register the CRM Compensator 
// can directly pass in BSTR * or C-style wide string 
// can also accept stringized GUID of form 

//{7BB101F1-92B6-11d1-82EC-00A0C91EEDE9} instead of Prog Id 
[id(2), helpstringC'method RegisterCompensator)] 
HRESULT RegisterCompensator( 

[in] LPCWSTR IpcwstrProgldCompensator, 
[in] LPCWSTR IpcwstrDescription); 

// for use by VB - write a collection of variants to the log 
[id(3), helpstringf method WriteLogRecordVariants")] 
HRESULT WriteLogRecordVariants([inl lUnknown * punkCollection); 

// force all log records (that have been written so far) to disk 
{id(4). helpstringf method ForceLog")] 
HRESULT ForceLogO; 

// forget the last log record written by this instance of this interface 
[id{5). helpstringfmethod ForgetLogRecord")! 
HRESULT ForgetLogRecordO; 

// force an abort of the current transaction 
[id(6), helpstring ("method ForceTransactionToAbort")] 
HRESULT ForceTransactionToAbortO; 

// for use by VC - write an unstructured record to the log 
// NOTE: implements gather using an array of blobs 
HRESULT WriteLogRecord( 

[in, sizeJs(cBlob)l BLOB rgBlobfl. [in] ULONG cBlob); 

\ 
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/ 

302 typedef enum tagCrmFlags 
\ { crmflag_ForgetTarget 

cnmflag_WrittenDuringPrepare 
crmfIag_WrittenDuringCommit 
crmflag_WrittenDuringAbort 
crmflag_WrittenDuringRecovery 
crmflag^Written DuringReplay 
crmflag_ReplaylnProgress 
} CrmFlags; 

typedef struct tagCrmLogRecordRead 
{ DWORD dwCrmFlags; 

DWORD dwSequenceNumber; 
BLOB blobUserData; 
} CrmLogRecordRead; 

\ 



0x00000001, 
0x00000002, 
0x00000004. 
0x00000008. 
0x00000010, 
0x00000020. 
0x00000040. 
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/ 

303 [ object. 
\ uuid(F0BAF8E4-7804-1 1d1-82E9-00A0C91 EEDE9). 

helpstringflCrmCompensatorVariants Interface"), 
pointer_default(unique)l 
interface ICmnCompensatorVariants : lUnknown { 
[id(1), helpstring ("method SetLogControlVariants")] 
HRESULT SetLogControlVariants([inI ICmiLogControl * pLogControl); 

[id(2). helpstringfrnethod BeginPrepareVariants")] 
HRESULT BeginPrepareVariantsQ; 

[id(3), helpstringC'method PrepareRecordVariants")] 
HRESULT PrepareRecordVariants( 
[in] VARIANT * pLogRecord, 
[out. retval] VARIANT^BOOL * bForget); 

rid{4), helpstringfmethod EndPrepareVariants")J 
HRESULT EndPrepareVariants( 

[out retvall VARIANT.BOOL * bOkToPrepare); 

pd(5), helpstringfmethod BeginCommitVariants")] 
HRESULT BegmCommitVariantsdin] VARIANT^BOOL bRecovery); 

[id(6), helpstringC'method CommitRecordVariants")] 
HRESULT CommitRecordVariants( 
[in] VARIANT * pLogRecord. 
[out. retvall VARIANT^OOL * bForget); 

[id(7), helpstring("method EndCommitVariants")] 
HRESULT EndCommitVariantsQ; 

[id(8), helpstringC'method BeginAbortVariants")} 
HRESULT BeginAbortVariants([in] VARIANT^BOOL bRecovery); 

[id(9). helpstringC'method AbortRecordVariants")] 
HRESULT AbortRecordVariants( 
[in] VARIANT * pLogRecord, 
[out. retval] VARlANT_BOOL * bForget); 



\ 



[id(10). helpstringC'method EndAbortVariants")] 
HRESULT EndAbortVariantsO: 
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/ 



304 



[ object, 

uuld(BBC01830-8D3B-11d1-82EC-00A0C91EEDE9). 
helpstringC'ICrmCompensator Interface"), 

pointer_default(unique)] 
interface iCrmCompensator : (Unknown 

{ 

HRESULT SetLogControl([in] ICrmLogControl * pLogControl): 

// PREPARE - phase 1 - log records delivered in fooA^ard order 
// NOTE: log records are delivered as a single blob 
HRESULT BeglnPrepareO; 

HRESULT PrepareRecord( 

[in] Crm Log Record Read crmLogRec, 
[out. retval] BOOL * fForget); 

HRESULT EndPrepare((out, retval] BOOL * fOkToPrepare): 

// COMMIT - phase 2 - log records delivered in fooA^ard order 
HRESULT BeginCommit([in] BOOL fRecovery); 

HRESULT CommitRecord( 

pn] CrmLogRecordRead crmLogRec, 
[out, retval] BOOL * fForget); 

HRESULT EndCommitO: 

// ABORT - phase 2 - log records delivered In reverse order 
HRESULT BeginAbort([in] BOOL fRecovery); 

HRESULT AbortRecord( 

[in] CrmLogRecordRead crmLogRec, 
[out, retval] BOOL * fForget); 

HRESULT EndAbortO; 

, }: 
\ 
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306 interface ILogRecover : (Unknown 

HRESULT AppendRecord( 

[in] LOGRECORDJ/VRITE* logrec. 
{inj BOOL fForceNow, 
[in] ILogAsyncCompletion* pasync, 
[out] LSN* pisn); 
HRESULT AppendCompensationRecord ( 
[in] LOGRECORD_READ* logrec. 
[in] LOGCOMPENSATIONRECORD* dr. 
[in] BOOL fForceNow, 
[in] ILogAsyncCompletion* pasync, 
[out] LSN* pIsn ); 
HRESULT ReadRecord ( 
[in] LSN Isn, 

[out] LOGREC0RD_READ* pRec. 
[in] ILogAsyncCompletion* pasync ); 
HRESULT Force ( 

[in] LSN IsnMinToForce. 
[in] ILogAsyncCompletion* pasync ); 
HRESULT Recover ( 

[In] ILogAsyncCompletion* pasync ); 
HRESULT TakeCheckpoInt ( 

[in] ILogAsyncCompletion* pasync ); 
HRESULT RollBackTransaction ( 
[in] LSN IsnSavePoint, 
[in] XACTUOW* puow. 
[in] ILogAsyncCompletion* pasync ); 
HRESULT GetLogBound ( 

[out] LSN* Isn ); 
HRESULT GetLastLSNOfTransaction { 
[in] XACTUOW* puow, 
[out] LSN* Isn ); 

}: 

\ 
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/ : . 

308 interface ILogRecoverClerk : iPersist 

\ { 

HRESULT BeginRecovery ( 
lin] ILogRecover*.plog ); 
HRESULT AnalyzeRecord ( 

[in] LOGRECORD_READ* logrec ); 
HRESULT GetMinRedoLSN ( 

[out] LSN* Isn ): 
HRESULT BeginRedoPass ( ); 
HRESULT RedoRecord ( 

linl LOGREC0RD_READ* logrec ); 
HRESULT BeginUndoPass ( ); 
HRESULT UndoRecord ( 

[in] LOGRECORD_READ* logrec. 
[outl LSN* IsnCLR ); 
HRESULT EndRecovery ( ); 
HRESULT WriteCheckpoint ( 

[in.unlque] ILogAsyncCompletion* pasync. 
[out] LSN* IsnMinlnUse ); 
HRESULT RollbackRecord ( 

[in] LOGRECORD_READ* logrec. 
[out] LSN* IsnCLR ): 

, }: 
\ 
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\ 



interface ILogRecoverClerkPhaseNotification : iUnknown 

{ ' ■ 

HRESULT OnPrepare ( 
[inl XACTUOW* uow, 
[in] ILogRecover* pLog ); 
HRESULT OnCommit ( 
pn] XACTUOW* uow, 
[in] ILogRecover* pLog ); 
HRESULT OnAbort ( 
[in] XACTUOW* uow. 
[in] ILogRecover* pLog ); 
HRESULT OnlnDoubt ( 
[in] XACTUOW' uow. 
[in] ILogRecover* pLbg ); 

}: 
\ 
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interface ILogRecoverClerkRegistration : lUnknown 
{ 

HRESULT RegisterClerk ( 

[in.unique] ILogRecoverClerk* pclerk, 
(in]BOOLfFaultlnable); 
HRESULT GetClerk ( 

[in] REFCLSID clsidClerk. 
[in] REFHD iid, 

[out, iid_is(iid)i LPVOID* ppv ); 
HRESULT UnregisterClerk ( 
[in] ILogRecoverClerk* pclerk ); 

}: 
\ 
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interface ILog : lUnknown 
{ 

HRESULT Force ( [in] LSN IsnMinToForce ); 
HRESULT AppendRecord ( 
[in] BLOB* rgBlob. 
[in] ULONG cBlob. 
[in] BOOL fForceNow. 
(out]LSN*lsn ); 
HRESULT ReadRecord ( 
[in] LSN IsnToRead, 
[out] LSN* plsnPrev. 
[out] LSN* pIsnNext. 
[out] LPVOID* ppvData, 
[out] ULONG* pcbData. 
[out] PVOID* ppvToken ); 
HRESULT ReadRecordRelease ([in] PVOID pvToken); 
HRESULT ReadRecordPrefix ( 
[in] LSN IsnToRead, 
[out] LSN* plsnPrev. 
[out] LSN* pisnNext, 
[out] LPVOID pvData. 
[in.out] ULONG* pcbData, 
[out] ULONG* pcbRecord ); 
HRESULT GetLogLimits ( 
[out] LSN* IsnFirst, 
[out] LSN* IsnLast ): 
HRESULT TmncatePrefix ([in] LSN IsnFirstToKeep ): 
HRESULT SetAccessPolicyHint ( 

[in] RECORD_READING_POLICY policy ); 

}: 

\ 
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316 ( 
^ object, 

uuid(9C51D821-C98B-11d1-82FB-OOA0C91EEDE9). 
helpstringC'ICrmFormatLogRecords Interface"), 
pojnter_default(unique) 

] 

interface ICnnFormatLogRecords : lUnknown 
{ 

[id(1), helpstring ("method GetColumnCount")] 
HRESULT GetColumnCount([out] long *plColumnCount); 

[id(2). heIpstring("method GetColumnHeaders")] 
HRESULT GetColumnHeadersdout] LPVARIANT pHeaders); 

[id(3). helpstring("method GetColumn")] 
HRESULT GetColumn( 

(In] CmnLogRecordRead CrmLogRec, 
[out] LPVARIANT pFomfiattedLogRecord); 

[id(4), helpstring("method GetColumnVariants")] 
HRESULT GetColumnVariants( 
[In] VARIANT LogRecord. 
[out] LPVARIANT pFomnattedLogRecord); 

}: 
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typedef enum tagCrmTransactionState 
{ TxState_Active, 
TxState_Committed. 
TxState_Aborted. 

TxStateJndoubt. } CrmTransactionState; 

// ICrmMonitorLogRecords - this is used to Inspect specific log records 
// It is implemented by the CRM clerk 
I 

object. 

uuid(70C8E441-C7ED-11d1-82FB.00A0C91EEDE9), 
helpstringflCrmMonitorLogRecords Interface"), 
pointer_default(unique)] 
interface ICrmMonitorLogRecords : lUnknown 
{ // how many log records? (write records only) 
[propget. id(1), helpstringfproperty Count")] 
HRESULT Count([out. retval] long *pVal): 

// current state of the transaction? 
[propget. id(2), helpstringfproperty TransactionState")] 
HRESULT TransactionState([out, retval] CnnTransactionState *pyal): 

// does this CRM clerk have structured records? 
[propget, id(3), helpstringfproperty StructuredRecords")] 
HRESULT StructuredRecords([out, retval] VARIANT_BOOL *pVal); 

// get the log record indicated by the zero based index # VC version 
[id(4), helpstringfmethod GetLogRecord")] 
HRESULT GetLogRecord( 
[in] DWORD dwindex. 

(In, out] CrmLpgRecordRead *pCrmLogRec); 
// VB version 

[id(5), helpstring("method GetLogRecordVariants")] 
HRESULT GetLogRecordVarlants( 
[in] VARIANT IndexNumber, 
[out. retval] LPVARIANT pLogRecord); 

\ 
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319 // ICrmMonitorClerks - this is used to find out which clerk is of interest 
'\ // It is implemented by the clerks collection object 
[ object, 

uuid(70C8E442-C7ED-1 1d1-82FB-O0A0C91EEDE9), 
dual, 

helpstringC'ICrmMonitorClerks Interface"). 
pointer_default(unique)l 
interface ICmnMonitorClerks : IDispatch 

{ // index is numeric, retums ClerklnstanceClsid as a VT_BSTR 
[id(DISPID_VALUE). he!pstring("method Item")] 
HRESULT ltem([in] VARIANT Index, [out, retval] LPVARIANT pitem); 

[propget, id(DISPID_NEWENUM), heipstringCproperty _NewEnum"). 
restricted] 

HRESULT _NewEnum([out. retval] LPUNKNOWN *pVal); 

Ipropget, id{1). helpslringfproperty Count")] 
HRESULT Count([out. retval] long •pVal); 

// index Is numeric OR index is ClerklnstanceClsid as VT_BSTR - 
// returns value as VT_BSTR 
[id(2), heIpstring("method ProgldCompensator'*)] 
HRESULT ProgldCompensator( 
[in] VARIANT Index, 
[out. retval] LPVARIANT pltem); 

[id{3), helpstring("method Description")] 

HRESULT Description([in] VARIANT Index, [out. retval] LPVARIANT pltem); 

[id(4), helpstringfmethod TransactionUOW")] 
HRESULT TransactionUOW( 
[inj VARIANT Index, 
[out. retval] LPVARIANT pltem); 

[id(5), helpstringC'method Activityld")] 

HRESULT Activityid([in] VARIANT Index, [out. retval] LPVARIANT pltem); 

}: 
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320 // ICrmMonitor - this is implemented by the CRM recovery clerk 
\ // It is used to get first the ICrmMonitorClerks collection, then the clerk itself 



{ 

object, 

uuid(70C8E443-C7ED-1 1d1-82FB-00A0C91 EEDE9). 

helpstringC'ICrmMonitor Interface"), 

pointer_default{unique)] 
interface ICrmMonitor : lUnknown 
{ 

// gets a snapshot of the cun-ent state of the list of CRM clerks 

(id(1). helpstringC'method GetClerks")] 

HRESULT GetClerksaout. retvalj ICrmMonitorClerks "pClerks): 



// get an ICmiMonitorLogRecords interface on the specified CRM clerk 
// NOTE: could return E_FAIL if that CRM clerk has completed 
// index is ClerklnstanceClsid as a VT_BSTR, returns 
// ICmiMonitorLogRecords as VT_UNKNOWN 
[id(2). helpstringf'method HoldClerk")] 

HRESULT HoldClerk([in] VARIANT Index, (out. retval] LPVARIANT pltem); 

}: 
\ 
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